Referencia de la API de Patu

POST /v1/compress

Comprime una imagen. Devuelve los bytes (en línea, por defecto) o un manifiesto JSON (almacenado).

En modo en línea, el formato devuelto también respeta la cabecera Accept cuando no se define formats.

Respuesta en línea

Los bytes de la imagen, más cabeceras que describen el resultado:

Respuesta almacenada (manifiesto)

{
  "id": "<64-hex content hash>",
  "url": "https://cdn.patu.dev/a/<id>",
  "original": { "width": 1024, "height": 683, "bytes": 240133, "format": "jpeg" },
  "variants": [
    { "format": "avif", "width": 1024, "height": 683, "bytes": 30215,
      "score": 81.5, "url": "https://cdn.patu.dev/a/<id>/1024.avif",
      "integrity": "sha384-…" }
  ],
  "created_at": "2026-06-29T12:00:00Z"
}

La url raíz es una URL con negociación de contenido: el edge devuelve el mejor formato que permite la cabecera Accept de la solicitud. Cada url de variante es una URL explícita, inmutable y direccionada por contenido para un formato y ancho exactos. Las URLs son absolutas en cdn.patu.dev cuando la CDN está activada (por defecto), o relativas al pod /v1/asset/<id>/… cuando está desactivada. Volver a enviar la misma imagen con nuevos widths extiende el manifiesto solo con los anchos nuevos; una solicitud idéntica se deduplica y devuelve el manifiesto existente sin cambios. Cada variante lleva su token integrity, y el edge lo sirve como X-Patu-Integrity.

Recursos que no son imágenes: JS, CSS, SVG y fuentes

El mismo endpoint /v1/compress (en línea o mode=stored) optimiza texto y fuentes. No tienen bytes mágicos, así que enrútalos con el Content-Type de la solicitud.

La salida nunca supera a la entrada. X-Patu-Format es js, css, woff2 o svg, y X-Patu-Score no aplica (-1). El código y las fuentes almacenados se sirven desde el edge igual que las imágenes, con la misma integrity.

Para JS y CSS, compara X-Patu-Encoded-Bytes, no X-Patu-Output-Bytes. La minificación por sí sola (Output-Bytes) es solo unos pocos puntos porcentuales; la verdadera ganancia es minificación más el Brotli del edge, que es lo que reporta Encoded-Bytes (el tamaño que cruza la red): en un corpus real eso es aproximadamente -90% en JS y -93% en CSS frente al código fuente sin procesar.

# minify a stylesheet
curl -X POST "https://patu.dev/v1/compress" \
  -H "X-Api-Key: $PATU_KEY" -H "Content-Type: text/css" \
  --data-binary @app.css -o app.min.css

# convert + subset a font to a Latin WOFF2
curl -X POST "https://patu.dev/v1/compress?subset-unicodes=0-FF,20AC" \
  -H "X-Api-Key: $PATU_KEY" -H "Content-Type: font/ttf" \
  --data-binary @Inter.ttf -o Inter.woff2

Optimización de EPUB

POST /v1/epub optimiza un contenedor EPUB completo: las imágenes incrustadas pasan por la misma búsqueda de calidad que /v1/compress, y las fuentes TTF/OTF se subconjuntan a los glifos que el libro realmente usa. Envía los bytes en bruto del .epub como cuerpo de la solicitud.

La cuota es una unidad por imagen procesada más una por fuente subconjuntada, contada desde el manifiesto antes de que se ejecute cualquier codificación. Una solicitud rechazada por cuota, tamaño o DRM no consume nada.

Síncrono vs. asíncrono

Los cuerpos de 10 MB (10,485,760 bytes) o menos se optimizan en línea y se devuelven directamente en la respuesta. Los cuerpos más grandes se encolan y se responden con 202:

{ "id": "a1b2c3d4e5f67890", "status_url": "/v1/epub/a1b2c3d4e5f67890" }

Consulta GET /v1/epub/{id}: 202 mientras el trabajo sigue en curso, 200 con el .epub optimizado cuando termina. Los resultados asíncronos caducan 24 horas después de completarse. Un reinicio del pod descarta cualquier trabajo aún pendiente en memoria; su GET responde entonces 404 — vuelve a enviar la solicitud original.

Cabeceras de respuesta

Tamaño máximo de subida por nivel

Errores

# optimize a book (sync if <= 10 MB)
curl -X POST "https://patu.dev/v1/epub" \
  -H "X-Api-Key: $PATU_KEY" \
  --data-binary @book.epub -o book.optimized.epub

# a larger book: submit, then poll the async result
curl -X POST "https://patu.dev/v1/epub" -H "X-Api-Key: $PATU_KEY" \
  --data-binary @big-book.epub
curl "https://patu.dev/v1/epub/a1b2c3d4e5f67890" -H "X-Api-Key: $PATU_KEY" \
  -o big-book.optimized.epub

Optimización de CBZ/CBR

POST /v1/cbz optimiza un archivo de cómic completo: cada página pasa por la misma búsqueda de calidad en el mismo formato que /v1/compress (una página JPEG sigue siendo JPEG, una página PNG sigue siendo PNG), todo lo demás en el archivo - ComicInfo.xml, cualquier otro archivo adicional - pasa sin tocarse, y el orden y los nombres de las páginas nunca cambian. Envía los bytes en bruto del .cbz o .cbr como cuerpo de la solicitud; un archivo CBR (RAR) se convierte de forma transparente a CBZ.

La cuota es una unidad por página procesada, contada desde el archivo antes de que se ejecute cualquier codificación. Una solicitud rechazada por cuota o tamaño no consume nada.

Siempre asíncrono

Toda solicitud /v1/cbz se encola y se responde con 202 - no hay vía síncrona, ya que incluso la búsqueda de calidad de página completa de un archivo de cómic pequeño puede tardar un rato:

{ "id": "a1b2c3d4e5f67890", "status_url": "/v1/cbz/a1b2c3d4e5f67890" }

Consulta GET /v1/cbz/{id}: 202 mientras el trabajo sigue en curso, 200 con el .cbz optimizado cuando termina. Los resultados asíncronos caducan 24 horas después de completarse. Un reinicio del pod descarta cualquier trabajo aún pendiente en memoria; su GET responde entonces 404 - vuelve a enviar la solicitud original.

Cabeceras de respuesta (en GET)

Errores

# submit a comic archive, then poll the async result
curl -X POST "https://patu.dev/v1/cbz" -H "X-Api-Key: $PATU_KEY" \
  --data-binary @issue-01.cbz
curl "https://patu.dev/v1/cbz/a1b2c3d4e5f67890" -H "X-Api-Key: $PATU_KEY" \
  -o issue-01.optimized.cbz

Optimización de Office

POST /v1/office optimiza un documento de Office completo (.docx, .pptx, .odt, .odp, .ods): las imágenes incrustadas pasan por la misma búsqueda de calidad en el mismo formato que /v1/compress (una imagen JPEG sigue siendo JPEG, una PNG sigue siendo PNG), todo lo demás - marcado, estilos, relaciones, objetos incrustados - pasa sin tocarse. El formato del documento nunca cambia: no hay conversión, ni redimensionado (sin max_width) ni elección de profile. Envía los bytes en bruto del documento como cuerpo de la solicitud. .xlsx (hojas de cálculo OOXML) se rechaza por nombre - ver Rechazos abajo - .ods sí se acepta.

La cuota es una unidad por imagen procesada, contada desde el documento antes de que se ejecute cualquier codificación. Una solicitud rechazada por cuota, tamaño o uno de los rechazos siguientes no consume nada.

Síncrono vs. asíncrono

Los cuerpos de 10 MB (10,485,760 bytes) o menos se optimizan en línea y se devuelven directamente en la respuesta. Los cuerpos más grandes se encolan y se responden con 202:

{ "id": "a1b2c3d4e5f67890", "status_url": "/v1/office/a1b2c3d4e5f67890" }

Consulta GET /v1/office/{id}: 202 mientras el trabajo sigue en curso, 200 con el documento optimizado cuando termina. Los resultados asíncronos caducan 24 horas después de completarse. Un reinicio del pod descarta cualquier trabajo aún pendiente en memoria; su GET responde entonces 404 - vuelve a enviar la solicitud original.

Rechazos

Un documento se rechaza por completo, antes de cualquier codificación, cuando coincide con uno de estos - cada uno tiene su propio mensaje 400 distinto:

Errores

# optimize a document (sync if <= 10 MB)
curl -X POST "https://patu.dev/v1/office" \
  -H "X-Api-Key: $PATU_KEY" \
  --data-binary @report.docx -o report.optimized.docx

Optimización de PDF

POST /v1/pdf optimiza un PDF completo y devuelve un PDF. Las imágenes JPEG incrustadas pasan por la misma búsqueda de calidad que /v1/compress (un JPEG sigue siendo un JPEG, una imagen en escala de grises sigue en escala de grises), y los flujos mal codificados (ASCII85, RunLength, LZW, Flate débil) se recomprimen sin pérdida. El texto, las fuentes, los dibujos vectoriales, los enlaces y los formularios no se tocan; las imágenes JPEG 2000, JBIG2 y CCITT (típicas de los escaneos) se dejan como están. Antes de enviar el resultado, cada página se renderiza y se compara con el original; si una página difiere, o si nada se redujo, el documento original vuelve sin cambios con X-Patu-Passthrough: true. target (ssimulacra2, 85 por defecto) fija el objetivo de calidad de las imágenes. Un PDF enviado a POST /v1/compress pasa por el mismo proceso, en línea hasta 10 MB, y también vuelve como PDF.

La cuota es una unidad por cada JPEG incrustado realmente recodificado; la pasada sin pérdida sobre los flujos es gratuita. Una petición rechazada por cuota, tamaño o uno de los rechazos siguientes no consume nada.

Síncrono vs. asíncrono

Los cuerpos de 10 MB o menos (10.485.760 bytes) se optimizan en línea y se devuelven directamente en la respuesta. Los cuerpos más grandes se encolan y se responden con 202:

{ "id": "a1b2c3d4e5f67890", "status_url": "/v1/pdf/a1b2c3d4e5f67890" }

Consulte GET /v1/pdf/{id}: 202 mientras el trabajo sigue en curso, 200 con el PDF optimizado cuando termina. Los resultados asíncronos caducan 24 horas después de terminar. Un reinicio del pod descarta cualquier trabajo aún pendiente en memoria; su GET responde entonces 404 - reenvíe la petición original.

Rechazos

Un documento se rechaza entero, antes de cualquier codificación, cuando coincide con uno de estos casos; cada uno tiene su propio mensaje 400:

Errores

# optimize a PDF (sync if <= 10 MB)
curl -X POST "https://patu.dev/v1/pdf" \
  -H "X-Api-Key: $PATU_KEY" \
  --data-binary @invoice.pdf -o invoice.optimized.pdf

POST /v1/compress/batch

Comprime muchas imágenes en una sola solicitud (solo modo almacenado). Envía multipart/form-data con una parte de archivo por imagen; widths, formats, target y async se aplican a todas las partes.

{
  "results": [
    { "id": "…", "original": {…}, "variants": [{…}], "created_at": "…" },
    { "error": "image exceeds the pixel limit", "status": 413 }
  ]
}

Un slot por imagen de entrada, en orden. Una imagen defectuosa solo falla en su slot, no en todo el lote. Con async=1 la respuesta es 202 y cada slot es un manifiesto pendiente (sus URLs responden 202 hasta que se codifican). Cada imagen cuenta como una unidad de cuota mensual; el lote completo es una unidad de límite de tasa. Límites: como máximo PATU_BATCH_MAX (20) partes y un tamaño total de payload acotado por solicitud.

GET /v1/asset/{id}

Obtén un recurso almacenado por negociación de contenido. La respuesta lleva ETag, Vary: Accept y un Cache-Control cacheable.

La negociación sigue la cabecera Accept (RFC 9110, incluidas las exclusiones q=0): Accept: image/jpeg devuelve JPEG, image/avif;q=0 omite AVIF, y */* o ninguna cabecera devuelve el mejor (AVIF). Para un control determinista del formato sin importar el cliente, usa las URLs explícitas {width}.{ext} (por ejemplo en etiquetas <source type>).

Otros endpoints

Límites y contrapresión

Los límites por clave evitan que un solo inquilino sature el servicio. Los valores de abajo son los del nivel Free; los niveles de pago los aumentan. Respeta Retry-After y te ajustarás al ritmo óptimo.

Ambas ventanas de cuota se reinician a las 00:00 UTC (la diaria cada noche, la mensual el día 1). Una solicitud rechazada con 429 o 413 no cuenta contra tu cuota. Un 503 significa que los codificadores están momentáneamente saturados, no que la solicitud estuviera mal: espera Retry-After segundos y vuelve a enviarla. Los aciertos de caché y los reenvíos de imágenes ya almacenadas nunca están limitados por el codificador. Los widths nunca aumentan la resolución más allá del ancho de origen, así que una solicitud de un ancho mayor que el original devuelve el ancho original en su lugar.

Errores

Los cuerpos de error son JSON: {"error": "..."}.