API Documentation

API de Conversión de Imágenes#

Una sola API REST convierte imágenes entre JPEG, PNG, WebP, HEIC y SVG, renderiza páginas PDF como JPEG y comprime imágenes sin cambiar su formato. Cada endpoint acepta una carga multipart/form-data y convierte de forma síncrona usando Pillow, CairoSVG, pillow-heif o PyMuPDF según el par de formatos. Por defecto, la respuesta es el archivo convertido sin procesar; establece direct_download=false para recibir en su lugar metadatos JSON con una URL de descarga firmada.

Conversiones admitidas#

Conversión Endpoint Descripción
JPEG a PNG POST /v1/convert/jpeg-to-png Convierte una carga .jpeg/.jpg en un PNG sin pérdida con fidelidad de color completa.
PNG a JPEG POST /v1/convert/png-to-jpeg Convierte un .png en un JPEG de máxima calidad, componiendo las áreas transparentes sobre un fondo blanco.
JPEG a SVG POST /v1/convert/jpeg-to-svg Incrusta el JPEG en base64 como un URI de datos dentro de un elemento <image> de SVG. Es un contenedor rasterizado, no una vectorización.
SVG a JPEG POST /v1/convert/svg-to-jpeg Rasteriza el SVG con CairoSVG y devuelve un JPEG, componiendo la transparencia sobre un fondo blanco.
JPEG a HEIC POST /v1/convert/jpeg-to-heic Codifica una carga .jpeg/.jpg como un archivo HEIC de alta calidad usando el códec HEIF.
HEIC a JPEG POST /v1/convert/heic-to-jpeg Decodifica una carga .heic o .heif (por ejemplo, fotos de iPhone) y produce un JPEG de alta calidad.
JPEG a WebP POST /v1/convert/jpeg-to-webp Produce un WebP de alta calidad con un tamaño de archivo menor que el JPEG equivalente para entrega web.
WebP a JPEG POST /v1/convert/webp-to-jpeg Convierte un .webp en JPEG, componiendo cualquier área transparente sobre un fondo blanco.
PNG a SVG POST /v1/convert/png-to-svg Incrusta el PNG como un URI de datos en base64 dentro de un contenedor SVG que coincide con las dimensiones en píxeles de la imagen. No es vectorización.
SVG a PNG POST /v1/convert/svg-to-png Rasteriza el SVG con CairoSVG en su tamaño declarado, preservando la transparencia en el PNG de salida.
PNG a HEIC POST /v1/convert/png-to-heic Convierte un .png en HEIC, componiendo las áreas transparentes sobre un fondo blanco.
HEIC a PNG POST /v1/convert/heic-to-png Convierte una carga .heic o .heif en un PNG sin pérdida con fidelidad de color completa.
PNG a WebP POST /v1/convert/png-to-webp Convierte un .png en WebP preservando el canal alfa (transparencia).
WebP a PNG POST /v1/convert/webp-to-png Convierte un .webp en un PNG sin pérdida preservando la transparencia.
SVG a HEIC POST /v1/convert/svg-to-heic Renderiza el SVG con CairoSVG y lo codifica como HEIC a máxima calidad sobre un fondo blanco.
HEIC a SVG POST /v1/convert/heic-to-svg Decodifica el HEIC a PNG y lo incrusta como un URI de datos en base64 dentro de un contenedor SVG. No es vectorización.
SVG a WebP POST /v1/convert/svg-to-webp Renderiza el SVG con CairoSVG y lo codifica como WebP a máxima calidad preservando la transparencia.
WebP a SVG POST /v1/convert/webp-to-svg Decodifica el WebP a PNG y lo incrusta como un URI de datos en base64 dentro de un contenedor SVG. No es vectorización.
HEIC a WebP POST /v1/convert/heic-to-webp Convierte una carga .heic o .heif en un WebP de alta calidad, preservando el canal alfa si está presente.
WebP a HEIC POST /v1/convert/webp-to-heic Convierte un .webp en HEIC a máxima calidad, componiendo la transparencia sobre un fondo blanco.
PDF a JPEG POST /v1/convert/pdf-to-jpeg Renderiza cada página del PDF como un JPEG a 144 DPI; los PDF de una sola página devuelven un JPEG, los PDF de varias páginas devuelven un ZIP con un JPEG por página.
Comprimir imagen POST /v1/convert/compress-image Comprime PNG, JPEG o WebP sin cambiar el formato: optimización sin pérdida primero, con reducción de escala opcional (relación de aspecto bloqueada) hasta un presupuesto target_size_kb.

Convenciones comunes#

  • Autenticación: cada endpoint requiere una clave de API privada (X-API-Key: sk_...) o un token JWT de una clave pública (Authorization: Bearer <jwt_token>). Consulta Autenticación.
  • Forma de la solicitud: todos los endpoints aceptan multipart/form-data con un campo file obligatorio, además de los parámetros opcionales output_filename y direct_download. Los endpoints de rasterización de SVG (svg-to-png, svg-to-jpeg, svg-to-webp) también aceptan dimensiones opcionales en píxeles mediante width/height, y compress-image acepta un presupuesto opcional target_size_kb. Consulta Trabajos síncronos y asíncronos.
  • Respuestas: las conversiones se ejecutan de forma síncrona. Con direct_download=true (el valor por defecto) obtienes los bytes convertidos sin procesar; con direct_download=false obtienes metadatos JSON que incluyen presigned_url, object_key, filename, file_size y conversion_time_seconds.
  • Errores y límites: los endpoints devuelven 400 por entrada inválida o corrupta, 401 por credenciales faltantes o inválidas, 402 cuando se agota la cuota mensual de ops o se alcanza el límite de almacenamiento de tu plan, y 413 cuando un archivo supera el tamaño máximo de archivo de tu plan. Consulta Códigos de error.
  • Calidad: los endpoints de conversión codifican a la máxima calidad (no configurable). El tamaño de salida sí es configurable donde se indica arriba: width/height en los endpoints de rasterización de SVG, target_size_kb en compress-image.

Preguntas frecuentes#

¿Cómo convierto un formato de imagen con una API REST?#

Envía una solicitud POST multipart/form-data al endpoint /v1/convert/{source}-to-{target} correspondiente con tu imagen en el campo file, autenticada mediante X-API-Key o un token JWT Bearer. Por defecto, la API responde con el archivo convertido sin procesar; establece direct_download=false para obtener en su lugar metadatos JSON con una URL de descarga firmada.

¿Los endpoints de salida SVG vectorizan mi imagen?#

No. Los endpoints de JPEG, PNG, WebP y HEIC a SVG codifican en base64 la imagen rasterizada y la incrustan como un URI de datos dentro de un elemento <image> de SVG dimensionado según las dimensiones originales en píxeles. No convierten la imagen en trazados vectoriales, y la codificación en base64 añade aproximadamente un 33% al tamaño del archivo.

¿Qué ocurre con la transparencia durante la conversión?#

Depende del formato de salida. Las conversiones a JPEG y HEIC componen las áreas transparentes sobre un fondo blanco, porque esos formatos de salida se producen sin transparencia. Las conversiones a PNG y WebP preservan el canal alfa.

← markdown-to-html jpeg-to-png →