Patu API Reference

POST /v1/compress

Compress one image. Returns the bytes (inline, default) or a JSON manifest (stored).

For inline mode the returned format also honours the Accept header when formats is not set.

Inline response

The image bytes, plus headers describing the result:

Stored response (manifest)

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

The root url is one content-negotiated URL: the edge returns the best format the request's Accept allows. Each variant url is an explicit, immutable, content-addressed URL for one exact format and width. URLs are absolute on cdn.patu.dev when the CDN is enabled (the default), or pod-relative /v1/asset/<id>/… when it is off. Re-posting the same image with new widths extends the manifest with only the new widths; an identical request is de-duplicated and returns the existing manifest unchanged. Each variant carries its integrity token, and the edge serves it as X-Patu-Integrity.

Treat variant URLs as opaque — read them from the manifest rather than constructing them. When Patu's encoders improve, a re-posted asset is transparently re-encoded: the fresh manifest points at new variant URLs (a .vN name suffix), it reflects the formats and widths of that request, and every previously issued URL keeps serving its original bytes forever, so existing pages, caches and integrity pins are never broken.

Non-image assets: JS, CSS, SVG and fonts

The same /v1/compress endpoint (inline or mode=stored) optimizes text and fonts. They have no magic bytes, so route them with the request Content-Type.

Output never exceeds the input. X-Patu-Format is js, css, woff2 or svg, and X-Patu-Score does not apply (-1). Stored code and fonts are served from the edge like images, with the same integrity.

For JS and CSS, compare X-Patu-Encoded-Bytes, not X-Patu-Output-Bytes. Minification alone (Output-Bytes) is only a few percent; the real win is minify plus the edge's Brotli, which is what Encoded-Bytes reports (the size that crosses the wire): on a real corpus that is roughly -90% on JS and -93% on CSS versus the raw source.

# 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

EPUB optimization

POST /v1/epub optimizes a whole EPUB container: embedded images go through the same quality search as /v1/compress, and TTF/OTF fonts are subset to the glyphs the book actually uses. Send the raw .epub bytes as the request body.

Quota is one unit per image processed plus one per font subsetted, counted from the manifest before any encode runs. A request rejected for quota, size or DRM consumes nothing.

Sync vs. async

Bodies at or under 10 MB (10,485,760 bytes) are optimized inline and returned directly in the response. Larger bodies are queued and answered with 202:

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

Poll GET /v1/epub/{id}: 202 while the job is still running, 200 with the optimized .epub once it finishes. Async results expire 24 hours after completion. A pod restart drops any job still pending in memory; its GET then answers 404 — re-submit the original request.

Response headers

Max upload size by tier

Errors

# 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

CBZ/CBR optimization

POST /v1/cbz optimizes a whole comic archive: every page goes through the same same-format quality search as /v1/compress (a JPEG page stays a JPEG, a PNG page stays a PNG), everything else in the archive - ComicInfo.xml, any other sidecar file - passes through untouched, and page order and names never change. Send the raw .cbz or .cbr bytes as the request body; a CBR (RAR) archive is transparently converted to CBZ.

Quota is one unit per page processed, counted from the archive before any encode runs. A request rejected for quota or size consumes nothing.

Always async

Every /v1/cbz request is queued and answered with 202 - there is no synchronous path, since even a small comic archive's full-page quality search can take a while:

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

Poll GET /v1/cbz/{id}: 202 while the job is still running, 200 with the optimized .cbz once it finishes. Async results expire 24 hours after completion. A pod restart drops any job still pending in memory; its GET then answers 404 - re-submit the original request.

Response headers (on GET)

Errors

# 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

Office optimization

POST /v1/office optimizes a whole Office document (.docx, .pptx, .odt, .odp, .ods): embedded images go through the same same-format quality search as /v1/compress (a JPEG image stays a JPEG, a PNG stays a PNG), everything else - markup, styles, relationships, embedded objects - passes through untouched. The document's format never changes: there is no conversion, no resize (no max_width) and no profile choice. Send the raw document bytes as the request body. .xlsx (OOXML spreadsheets) is refused by name - see Refusals below - .ods is accepted.

Quota is one unit per image processed, counted from the document before any encode runs. A request rejected for quota, size or one of the refusals below consumes nothing.

Sync vs. async

Bodies at or under 10 MB (10,485,760 bytes) are optimized inline and returned directly in the response. Larger bodies are queued and answered with 202:

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

Poll GET /v1/office/{id}: 202 while the job is still running, 200 with the optimized document once it finishes. Async results expire 24 hours after completion. A pod restart drops any job still pending in memory; its GET then answers 404 - re-submit the original request.

Refusals

A document is refused whole, before any encode, when it matches one of these - each gets its own distinct 400 message:

Errors

# 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

PDF optimization

POST /v1/pdf optimizes a whole PDF and returns a PDF. Embedded JPEG images are re-encoded through the same quality search as /v1/compress (a JPEG stays a JPEG, a grayscale image stays grayscale), and wastefully encoded streams (ASCII85, RunLength, LZW, weak Flate) are recompressed losslessly. Text, fonts, vector drawings, links and forms are not touched; JPEG 2000, JBIG2 and CCITT images (typical of scans) are left as they are. Before the result ships, every page is rendered and compared with the original; if a page diverges, or if nothing got smaller, the original document comes back unchanged with X-Patu-Passthrough: true. target (ssimulacra2, default 85) sets the image quality goal. A PDF sent to POST /v1/compress goes through the same pipeline inline, up to 10 MB, and also comes back as a PDF.

Quota is one unit per embedded JPEG actually re-encoded; the lossless stream pass is free. A request rejected for quota, size or one of the refusals below consumes nothing.

Sync vs. async

Bodies at or under 10 MB (10,485,760 bytes) are optimized inline and returned directly in the response. Larger bodies are queued and answered with 202:

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

Poll GET /v1/pdf/{id}: 202 while the job is still running, 200 with the optimized PDF once it finishes. Async results expire 24 hours after completion. A pod restart drops any job still pending in memory; its GET then answers 404 - re-submit the original request.

Refusals

A document is refused whole, before any encode, when it matches one of these - each gets its own distinct 400 message:

Errors

# 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

Compress many images in one request (stored mode only). Send multipart/form-data with one file part per image; widths, formats, target and async apply to all parts.

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

One slot per input image, in order. A bad image fails only its slot, not the batch. With async=1 the response is 202 and each slot is a pending manifest (its URLs answer 202 until encoded). Each image counts as one monthly-quota unit; the whole batch is one rate-limit unit. Limits: at most PATU_BATCH_MAX (20) parts and a bounded total payload size per request.

GET /v1/asset/{id}

Fetch a stored asset by content negotiation. The response carries ETag, Vary: Accept and a cacheable Cache-Control.

Negotiation follows the Accept header (RFC 9110, including q=0 exclusions): Accept: image/jpeg returns JPEG, image/avif;q=0 skips AVIF, and */* or no header returns the best (AVIF). For deterministic format control regardless of the client, use the explicit {width}.{ext} URLs (e.g. in <source type> tags).

DELETE /v1/asset/{id}

Remove a stored asset you own (requires X-Api-Key). Returns 204 on success, 404 when the asset does not exist or is not yours. Assets are content-addressed and de-duplicated across accounts: deleting removes your reference, and the underlying files are physically deleted only when no other account still references the same content. Deletion is origin-side lifecycle cleanup — already-cached copies at the CDN edge drain on their own TTL.

Other endpoints

Limits & backpressure

Per-key limits keep one tenant from saturating the service. The values below are the Free tier; paid tiers raise them. Honour Retry-After and you will pace yourself optimally.

Both quota windows reset at 00:00 UTC (daily every night, monthly on the 1st). A request rejected with 429 or 413 does not count against your quota. A 503 means the encoders are momentarily full, not that the request was bad: back off for Retry-After seconds and resend. Cache hits and re-posts of already-stored images are never rate-limited by the encoder. widths are never upscaled past the source width, so a request for a width larger than the original returns the original width instead.

Errors

Error bodies are JSON: {"error": "..."}.