Referência da API do Patu

POST /v1/compress

Comprime uma imagem. Retorna os bytes (em linha, padrão) ou um manifesto JSON (armazenado).

No modo em linha, o formato retornado também respeita o cabeçalho Accept quando formats não é definido.

Resposta em linha

Os bytes da imagem, mais cabeçalhos descrevendo o resultado:

Resposta armazenada (manifesto)

{
  "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"
}

A url raiz é uma URL única com negociação de conteúdo: a borda retorna o melhor formato que o Accept da requisição permitir. Cada url de variante é uma URL explícita, imutável e endereçada por conteúdo para um formato e largura exatos. As URLs são absolutas em cdn.patu.dev quando a CDN está habilitada (o padrão), ou relativas ao pod, /v1/asset/<id>/…, quando está desabilitada. Reenviar a mesma imagem com novas widths estende o manifesto apenas com as larguras novas; uma requisição idêntica é deduplicada e retorna o manifesto existente sem alterações. Cada variante carrega seu token integrity, e a borda o serve como X-Patu-Integrity.

Recursos que não são imagens: JS, CSS, SVG e fontes

O mesmo endpoint /v1/compress (em linha ou mode=stored) otimiza texto e fontes. Eles não têm magic bytes, então são roteados pelo Content-Type da requisição.

A saída nunca excede a entrada. X-Patu-Format é js, css, woff2 ou svg, e X-Patu-Score não se aplica (-1). Código e fontes armazenados são servidos pela borda como imagens, com o mesmo integrity.

Para JS e CSS, compare X-Patu-Encoded-Bytes, não X-Patu-Output-Bytes. A minificação isolada (Output-Bytes) é de apenas alguns por cento; o ganho real é a minificação somada ao Brotli da borda, que é o que Encoded-Bytes reporta (o tamanho que trafega na rede): em um corpus real isso é de aproximadamente -90% em JS e -93% em CSS em relação à fonte bruta.

# 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

Otimização de EPUB

POST /v1/epub otimiza um contêiner EPUB inteiro: as imagens embutidas passam pela mesma busca de qualidade do /v1/compress, e as fontes TTF/OTF passam por subsetting para os glifos que o livro realmente usa. Envie os bytes brutos do .epub como corpo da requisição.

A cota é de uma unidade por imagem processada mais uma por fonte submetida a subsetting, contada a partir do manifesto antes de qualquer codificação rodar. Uma requisição rejeitada por cota, tamanho ou DRM não consome nada.

Síncrono vs. assíncrono

Corpos com até 10 MB (10,485,760 bytes) são otimizados em linha e retornados diretamente na resposta. Corpos maiores são enfileirados e respondidos com 202:

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

Consulte GET /v1/epub/{id}: 202 enquanto o job ainda está em execução, 200 com o .epub otimizado quando terminar. Resultados assíncronos expiram 24 horas após a conclusão. Um restart do pod descarta qualquer job ainda pendente em memória; seu GET então responde 404 — reenvie a requisição original.

Cabeçalhos de resposta

Tamanho máximo de upload por plano

Erros

# 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

Otimização de CBZ/CBR

POST /v1/cbz otimiza um arquivo de quadrinhos inteiro: cada página passa pela mesma busca de qualidade no mesmo formato do /v1/compress (uma página JPEG continua JPEG, uma página PNG continua PNG), tudo o mais no arquivo - ComicInfo.xml, qualquer outro arquivo complementar - passa intacto, e a ordem e os nomes das páginas nunca mudam. Envie os bytes brutos do .cbz ou .cbr como corpo da requisição; um arquivo CBR (RAR) é convertido de forma transparente para CBZ.

A cota é de uma unidade por página processada, contada a partir do arquivo antes de qualquer codificação rodar. Uma requisição rejeitada por cota ou tamanho não consome nada.

Sempre assíncrono

Toda requisição a /v1/cbz é enfileirada e respondida com 202 - não há caminho síncrono, já que mesmo a busca de qualidade em todas as páginas de um arquivo de quadrinhos pequeno pode demorar um pouco:

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

Consulte GET /v1/cbz/{id}: 202 enquanto o job ainda está em execução, 200 com o .cbz otimizado quando terminar. Resultados assíncronos expiram 24 horas após a conclusão. Um restart do pod descarta qualquer job ainda pendente em memória; seu GET então responde 404 - reenvie a requisição original.

Cabeçalhos de resposta (no GET)

Erros

# 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

Otimização do Office

POST /v1/office otimiza um documento do Office inteiro (.docx, .pptx, .odt, .odp, .ods): as imagens embutidas passam pela mesma busca de qualidade no mesmo formato do /v1/compress (uma imagem JPEG continua JPEG, uma PNG continua PNG), tudo o mais - marcação, estilos, relacionamentos, objetos embutidos - passa intacto. O formato do documento nunca muda: não há conversão, nem redimensionamento (nenhum max_width) e nenhuma escolha de profile. Envie os bytes brutos do documento como corpo da requisição. .xlsx (planilhas OOXML) é recusado pelo nome - veja Recusas abaixo - .ods é aceito.

A cota é de uma unidade por imagem processada, contada a partir do documento antes de qualquer codificação rodar. Uma requisição rejeitada por cota, tamanho ou uma das recusas abaixo não consome nada.

Síncrono vs. assíncrono

Corpos com até 10 MB (10,485,760 bytes) são otimizados em linha e retornados diretamente na resposta. Corpos maiores são enfileirados e respondidos com 202:

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

Consulte GET /v1/office/{id}: 202 enquanto o job ainda está em execução, 200 com o documento otimizado quando terminar. Resultados assíncronos expiram 24 horas após a conclusão. Um restart do pod descarta qualquer job ainda pendente em memória; seu GET então responde 404 - reenvie a requisição original.

Recusas

Um documento é recusado por completo, antes de qualquer codificação, quando corresponde a um destes - cada um recebe sua própria mensagem 400 distinta:

Erros

# 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

Otimização de PDF

POST /v1/pdf otimiza um PDF inteiro e devolve um PDF. As imagens JPEG incorporadas passam pela mesma busca de qualidade que /v1/compress (um JPEG continua JPEG, uma imagem em tons de cinza continua em tons de cinza), e os fluxos mal codificados (ASCII85, RunLength, LZW, Flate fraco) são recomprimidos sem perda. Texto, fontes, desenhos vetoriais, links e formulários não são tocados; as imagens JPEG 2000, JBIG2 e CCITT (típicas de digitalizações) ficam como estão. Antes de o resultado ser enviado, cada página é renderizada e comparada com o original; se uma página divergir, ou se nada ficou menor, o documento original volta inalterado com X-Patu-Passthrough: true. target (ssimulacra2, padrão 85) define o objetivo de qualidade das imagens. Um PDF enviado para POST /v1/compress passa pelo mesmo processo, em linha até 10 MB, e também volta como PDF.

A cota é de uma unidade por JPEG incorporado efetivamente recodificado; a passagem sem perda nos fluxos é gratuita. Uma requisição recusada por cota, tamanho ou uma das recusas abaixo não consome nada.

Síncrono vs. assíncrono

Corpos de até 10 MB (10.485.760 bytes) são otimizados em linha e devolvidos diretamente na resposta. Corpos maiores são enfileirados e respondidos com 202:

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

Consulte GET /v1/pdf/{id}: 202 enquanto o trabalho estiver em andamento, 200 com o PDF otimizado quando terminar. Os resultados assíncronos expiram 24 horas após a conclusão. Um reinício do pod descarta qualquer trabalho ainda pendente em memória; o seu GET responde então 404 - reenvie a requisição original.

Recusas

Um documento é recusado por inteiro, antes de qualquer codificação, quando corresponde a um destes casos; cada um tem a sua própria mensagem 400:

Erros

# 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 várias imagens em uma requisição (apenas modo armazenado). Envie multipart/form-data com uma parte de arquivo por imagem; widths, formats, target e async se aplicam a todas as partes.

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

Um slot por imagem de entrada, em ordem. Uma imagem ruim falha apenas em seu slot, não no lote inteiro. Com async=1 a resposta é 202 e cada slot é um manifesto pendente (suas URLs respondem 202 até serem codificadas). Cada imagem conta como uma unidade de cota mensal; o lote inteiro é uma unidade de rate limit. Limites: no máximo PATU_BATCH_MAX (20) partes e um tamanho total de payload limitado por requisição.

GET /v1/asset/{id}

Busca um recurso armazenado por negociação de conteúdo. A resposta carrega ETag, Vary: Accept e um Cache-Control cacheável.

A negociação segue o cabeçalho Accept (RFC 9110, incluindo exclusões q=0): Accept: image/jpeg retorna JPEG, image/avif;q=0 pula o AVIF, e */* ou nenhum cabeçalho retorna o melhor (AVIF). Para controle determinístico do formato independente do cliente, use as URLs explícitas {width}.{ext} (ex. em tags <source type>).

Outros endpoints

Limites e backpressure

Limites por chave impedem que um único tenant sature o serviço. Os valores abaixo são os do plano Free; planos pagos os aumentam. Respeite o Retry-After e você vai se ritmar de forma ideal.

As duas janelas de cota reiniciam à 00:00 UTC (diária toda noite, mensal no dia 1º). Uma requisição rejeitada com 429 ou 413 não conta na sua cota. Um 503 significa que os codificadores estão momentaneamente cheios, não que a requisição estava errada: aguarde Retry-After segundos e reenvie. Cache hits e reenvios de imagens já armazenadas nunca são limitados por taxa pelo codificador. As widths nunca são aumentadas além da largura original, então uma requisição para uma largura maior que a original retorna a largura original.

Erros

Corpos de erro são JSON: {"error": "..."}.