Formatos compatibles#

Cada extensión que la API acepta y cada formato que devuelve, con una tabla por familia de conversor. Las listas de esta página son las que comprueba el código, así que una extensión que falte está realmente rechazada, no simplemente sin documentar.

Si lo que quieres es el par (esta entrada, esa salida y la ruta del endpoint que las une), la matriz de conversiones tiene los 51 endpoints en una sola tabla fácil de recorrer.

Páginas web#

Cinco endpoints que reciben una URL en un cuerpo JSON en lugar de una carga de archivo.

Las capturas de pantalla son PNG. No existe opción de captura en JPEG ni en WebP: la llamada de captura está fijada a PNG en el código. Los dos endpoints website-to-* son solo asíncronos y siempre responden 202 con un batch_id y un output_format de zip.

Documentos a PDF#

Once endpoints de destino único, cada uno una carga multipart/form-data con el documento en el campo file. La salida siempre es un único PDF. El comodín anything-to-pdf es el duodécimo y tiene su propia sección más abajo.

El motor decide qué pdf_options son válidas. HTML y Markdown pasan por WeasyPrint y aceptan tamaño de página, orientación, márgenes, escala, encabezado y pie de página. Los nueve endpoints basados en LibreOffice toman la geometría de página del documento original, así que solo respetan grayscale y devuelven 400 cuando se establece explícitamente una opción de geometría.

anything-to-pdf#

POST /v1/convert/anything-to-pdf acepta 36 extensiones y siempre devuelve un PDF. Solo admite carga de archivo: no acepta URLs.

.bmp   .csv   .doc   .docx  .epub  .gif
.heic  .heif  .htm   .html  .jpeg  .jpg
.markdown     .md    .mdown .mkd   .numbers
.odp   .ods   .odt   .ots   .pages .pdf
.png   .ppt   .pptx  .rtf   .svg   .text
.tif   .tiff  .txt   .webp  .xhtml .xls
.xlsx

La extensión elige el motor:

Antes de enviar un archivo conviene conocer dos consecuencias de ese enrutamiento:

• La geometría de página (page_size, page_width, page_height, orientation, márgenes, scale, header, footer) solo se respeta para entradas HTML, Markdown, texto plano, EPUB, imagen y SVG. Si estableces una explícitamente sobre entrada de Office o PDF, la solicitud devuelve 400. grayscale funciona con cualquier entrada.
• Una carga de PDF se acepta y se devuelve tal cual, tras comprobar que los bytes empiezan por %PDF-. Combinado con grayscale, eso convierte a este endpoint en la vía para pasar a escala de grises un PDF existente.

anything-to-markdown#

POST /v1/convert/anything-to-markdown acepta 22 extensiones y siempre devuelve un único archivo .md en UTF-8.

.csv   .doc   .docx  .epub  .htm   .html
.markdown     .md    .mdown .mkd   .odp
.ods   .odt   .pdf   .ppt   .pptx  .rtf
.text  .txt   .xhtml .xls   .xlsx

Agrupadas según cómo se lee cada una:

Tres cosas con las que contar:

• Las imágenes se rechazan. .png, .jpg, .jpeg, .gif, .bmp, .webp, .tiff y .tif devuelven 400 con Image OCR ('<ext>') is not yet supported on this endpoint. Este endpoint no hace OCR, así que hoy una página escaneada dentro de un archivo de imagen no tiene ninguna vía para extraer texto.
• .ots, .pages y .numbers no se aceptan aquí, aunque anything-to-pdf sí admite las tres. Pásalas primero por anything-to-pdf, ya que .pdf sí está en la lista de arriba.
• La salida se normaliza antes de devolverse: CRLF pasa a LF, las series de tres o más líneas en blanco se colapsan y el archivo termina con un salto de línea.

La extracción se ejecuta con topes de recursos que protegen frente a cargas hostiles. Las entradas basadas en ZIP (EPUB, DOCX, XLSX, PPTX) se rechazan por encima de 400 MB declarados sin comprimir o de 10.000 entradas. Las tablas emitidas truncan las celdas a 500 caracteres y se detienen en 5.000 filas de cuerpo. El extractor de PDF tiene un tope de 2.000 páginas y 20.000 palabras por página.

Formatos de datos#

Once endpoints, todos cargas síncronas. La extensión del archivo debe coincidir con el endpoint al que lo envías.

Imágenes#

Veintidós endpoints: veinte conversiones entre JPEG, PNG, SVG, HEIC y WebP (todos los pares ordenados), más pdf-to-jpeg y compress-image. Lee esta tabla como «¿en qué puedo convertir esto?».

Los nombres de los endpoints siguen el par: jpeg-to-png, svg-to-webp, heic-to-jpeg, etc. Fíjate en que los endpoints de JPEG se escriben jpeg-, no jpg-, aunque se aceptan tanto archivos .jpeg como .jpg.

compress-image mantiene el formato de entrada: PNG entra, PNG sale. Su target_size_kb opcional debe ser al menos 1, y un valor menor devuelve 400 antes de gastar ninguna op.

pdf-to-jpeg devuelve un JPEG en bruto para un PDF de una sola página y un ZIP con page_1.jpeg hasta page_N.jpeg para uno de varias páginas. Cualquier salida de conversor que empiece con una firma ZIP se entrega con extensión .zip, que es la razón por la que un mismo endpoint puede darte dos tipos de contenido distintos.

Topes de píxeles#

Estos se comprueban aparte del límite de tamaño de archivo de tu plan, porque un archivo pequeño puede decodificarse en un mapa de bits enorme.

Las solicitudes de SVG que rompen un tope de dimensión devuelven 400 antes de contabilizar ninguna op. Si pasas solo width o solo height, el otro se deriva de la relación intrínseca del SVG; cuando esa relación no se puede leer, la solicitud falla con un 400 que pide ambos.

Tipos de medio de salida#

Las descargas directas llevan el tipo de medio asociado a la extensión de salida.

Todo lo que no esté en esa lista se sirve como application/octet-stream.

Entradas y salidas de V2#

Los endpoints de inteligencia web trabajan con outputs en lugar de con formatos de archivo.

POST /v2/perceive recibe una URL y devuelve cualquiera de un conjunto cerrado de outputs: markdown, html_cleaned, html_raw, screenshot, screenshot_full_page, pdf, links, images, structured. El valor por defecto es ["markdown", "structured"]. Todo salvo structured se escribe en almacenamiento y se devuelve como una URL de descarga firmada; structured vuelve inline en el cuerpo de la respuesta.

POST /v2/ingest/files reutiliza literalmente la lista de anything-to-markdown de arriba, así que se aceptan las mismas 22 extensiones y las imágenes se rechazan igual. Un solo trabajo admite hasta 200 archivos, con cada nombre de archivo de hasta 255 caracteres, y la salida del trabajo es un único archivo JSONL de fragmentos.

Cómo funciona la detección de formato#

Las cargas se comprueban dos veces, y ninguna de las dos comprobaciones mira el Content-Type de la solicitud. En ningún punto de la API hay una lista blanca de MIME para las cargas.

Primero, la extensión del nombre de archivo. Si el endpoint declara una lista de formatos aceptados y tu extensión no está en ella, la solicitud falla de inmediato:

{
    "detail": "Invalid file format '.txt' for json-to-xml. Allowed: .json"
}

Después, los bytes. La API inspecciona los primeros bytes de la carga y compara lo que encuentra con lo que declaraba la extensión. Reconoce PNG, JPEG, GIF, WebP, HEIC y HEIF, PDF, y los dos tipos de contenedor de Office (el contenedor ZIP que hay detrás de .docx, .xlsx, .pptx, ODF, iWork y EPUB, y el contenedor OLE2 más antiguo que hay detrás de .doc, .xls y .ppt).

Los formatos de texto se saltan la inspección por completo. JSON, CSV, XML, YAML, TOML, Markdown, HTML, SVG y el texto plano no tienen una firma fiable, así que su extensión se toma por válida y es el conversor el que informa del problema.

La inspección es deliberadamente conservadora. Solo rechaza un desajuste de alta confianza, es decir, una firma que reconoce y que pertenece a un grupo distinto del que declaraba la extensión. Una carga .png cuyos bytes son un JPEG se rechaza. Los bytes que no reconoce pasan sin más. Un desajuste devuelve 400:

{
    "detail": "File content does not match the 'jpeg-to-png' input type."
}

Los nombres de archivo se reescriben, no se rechazan, camino del almacenamiento: solo sobrevive el nombre base, se quitan .. y los caracteres <>:"|?*, y los espacios pasan a ser guiones bajos. En ingesta de archivos tienes la object key resultante.

Páginas relacionadas#

• Matriz de conversiones empareja cada entrada con su salida y la ruta de su endpoint.
• Ingesta de archivos cubre cómo enviar los bytes: carga multipart, una URL que la API obtiene, y los topes de tamaño que se aplican.
• Errores tiene la lista completa de mensajes para 400, 413 y 415.
• Límites de frecuencia y cuotas tiene los topes de subida por plan.