Riferimento API di Patu

POST /v1/compress

Comprimi una singola immagine. Restituisce i byte (in linea, valore predefinito) o un manifest JSON (archiviato).

Per la modalità in linea, il formato restituito rispetta anche l'intestazione Accept quando formats non è impostato.

Risposta in linea

I byte dell'immagine, più intestazioni che descrivono il risultato:

Risposta archiviata (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"
}

L'url radice è un unico URL negoziato per contenuto: l'edge restituisce il miglior formato consentito dall'Accept della richiesta. Ogni url di variante è un URL esplicito, immutabile e indirizzato per contenuto, per un formato e una larghezza esatti. Gli URL sono assoluti su cdn.patu.dev quando la CDN è abilitata (impostazione predefinita), oppure relativi al pod /v1/asset/<id>/… quando è disabilitata. Ripubblicare la stessa immagine con nuove widths estende il manifest con solo le nuove larghezze; una richiesta identica viene deduplicata e restituisce il manifest esistente invariato. Ogni variante porta il proprio token integrity, e l'edge lo serve come X-Patu-Integrity.

Asset non immagine: JS, CSS, SVG e font

Lo stesso endpoint /v1/compress (in linea o mode=stored) ottimizza testo e font. Non hanno magic byte, quindi instradali con il Content-Type della richiesta.

L'output non supera mai l'input. X-Patu-Format vale js, css, woff2 o svg, e X-Patu-Score non si applica (-1). Codice e font archiviati sono serviti dall'edge come le immagini, con lo stesso integrity.

Per JS e CSS, confronta X-Patu-Encoded-Bytes, non X-Patu-Output-Bytes. La sola minificazione (Output-Bytes) vale solo pochi punti percentuali; il vero guadagno è minify più il Brotli dell'edge, che è ciò che riporta Encoded-Bytes (la dimensione che attraversa la rete): su un corpus reale, questo significa circa -90% su JS e -93% su CSS rispetto alla sorgente grezza.

# 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

Ottimizzazione EPUB

POST /v1/epub ottimizza un intero container EPUB: le immagini incorporate passano per la stessa ricerca di qualità di /v1/compress, e i font TTF/OTF vengono sottoposti a subsetting sui glifi effettivamente usati dal libro. Invia i byte grezzi del file .epub come corpo della richiesta.

La quota è un'unità per immagine elaborata più una per font sottoposto a subsetting, conteggiata dal manifest prima che venga eseguita qualsiasi codifica. Una richiesta rifiutata per quota, dimensione o DRM non consuma nulla.

Sincrono e asincrono

I corpi fino a 10 MB (10,485,760 byte) inclusi vengono ottimizzati in linea e restituiti direttamente nella risposta. I corpi più grandi vengono accodati e la risposta è 202:

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

Esegui il polling di GET /v1/epub/{id}: 202 finché il job è ancora in esecuzione, 200 con l'.epub ottimizzato una volta terminato. I risultati asincroni scadono 24 ore dopo il completamento. Un riavvio del pod elimina ogni job ancora in sospeso in memoria; la sua GET risponde quindi 404: invia di nuovo la richiesta originale.

Intestazioni di risposta

Dimensione massima di caricamento per piano

Errori

# 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

Ottimizzazione CBZ/CBR

POST /v1/cbz ottimizza un intero archivio fumetto: ogni pagina passa per la stessa ricerca di qualità a parità di formato usata da /v1/compress (una pagina JPEG resta JPEG, una pagina PNG resta PNG), tutto il resto nell'archivio - ComicInfo.xml, qualsiasi altro file collaterale - passa invariato, e l'ordine e i nomi delle pagine non cambiano mai. Invia i byte grezzi del file .cbz o .cbr come corpo della richiesta; un archivio CBR (RAR) viene convertito in modo trasparente in CBZ.

La quota è un'unità per pagina elaborata, conteggiata dall'archivio prima che venga eseguita qualsiasi codifica. Una richiesta rifiutata per quota o dimensione non consuma nulla.

Sempre asincrono

Ogni richiesta a /v1/cbz viene accodata e la risposta è 202 - non esiste un percorso sincrono, perché anche la ricerca di qualità su tutte le pagine di un archivio fumetto piccolo può richiedere tempo:

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

Esegui il polling di GET /v1/cbz/{id}: 202 finché il job è ancora in esecuzione, 200 con il file .cbz ottimizzato una volta terminato. I risultati asincroni scadono 24 ore dopo il completamento. Un riavvio del pod elimina ogni job ancora in sospeso in memoria; la sua GET risponde quindi 404 - invia di nuovo la richiesta originale.

Intestazioni di risposta (su GET)

Errori

# 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

Ottimizzazione Office

POST /v1/office ottimizza un intero documento Office (.docx, .pptx, .odt, .odp, .ods): le immagini incorporate passano per la stessa ricerca di qualità a parità di formato usata da /v1/compress (un'immagine JPEG resta JPEG, una PNG resta PNG), tutto il resto - markup, stili, relazioni, oggetti incorporati - passa invariato. Il formato del documento non cambia mai: nessuna conversione, nessun ridimensionamento (nessun max_width) e nessuna scelta di profile. Invia i byte grezzi del documento come corpo della richiesta. .xlsx (fogli di calcolo OOXML) viene rifiutato in base al nome - vedi Rifiuti di seguito - .ods è accettato.

La quota è un'unità per immagine elaborata, conteggiata dal documento prima che venga eseguita qualsiasi codifica. Una richiesta rifiutata per quota, dimensione o uno dei rifiuti descritti di seguito non consuma nulla.

Sincrono e asincrono

I corpi fino a 10 MB (10,485,760 byte) inclusi vengono ottimizzati in linea e restituiti direttamente nella risposta. I corpi più grandi vengono accodati e la risposta è 202:

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

Esegui il polling di GET /v1/office/{id}: 202 finché il job è ancora in esecuzione, 200 con il documento ottimizzato una volta terminato. I risultati asincroni scadono 24 ore dopo il completamento. Un riavvio del pod elimina ogni job ancora in sospeso in memoria; la sua GET risponde quindi 404 - invia di nuovo la richiesta originale.

Rifiuti

Un documento viene rifiutato per intero, prima di qualsiasi codifica, quando corrisponde a uno di questi casi - ciascuno ha un proprio messaggio 400 distinto:

Errori

# 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

Ottimizzazione PDF

POST /v1/pdf ottimizza un intero PDF e restituisce un PDF. Le immagini JPEG incorporate passano per la stessa ricerca di qualità di /v1/compress (un JPEG resta un JPEG, un'immagine in scala di grigi resta in scala di grigi), e i flussi codificati in modo inefficiente (ASCII85, RunLength, LZW, Flate debole) vengono ricompressi senza perdita. Testo, font, disegni vettoriali, link e moduli non vengono toccati; le immagini JPEG 2000, JBIG2 e CCITT (tipiche delle scansioni) restano come sono. Prima di inviare il risultato, ogni pagina viene renderizzata e confrontata con l'originale; se una pagina diverge, o se nulla si è ridotto, il documento originale torna invariato con X-Patu-Passthrough: true. target (ssimulacra2, predefinito 85) fissa l'obiettivo di qualità delle immagini. Un PDF inviato a POST /v1/compress segue la stessa elaborazione, in linea fino a 10 MB, e torna anch'esso come PDF.

La quota è un'unità per ogni JPEG incorporato effettivamente ricodificato; il passaggio senza perdita sui flussi è gratuito. Una richiesta respinta per quota, dimensione o uno dei rifiuti seguenti non consuma nulla.

Sincrono e asincrono

I corpi fino a 10 MB (10.485.760 byte) vengono ottimizzati in linea e restituiti direttamente nella risposta. I corpi più grandi vengono messi in coda e ricevono un 202:

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

Interrogate GET /v1/pdf/{id}: 202 finché il lavoro è in corso, 200 con il PDF ottimizzato quando termina. I risultati asincroni scadono 24 ore dopo il completamento. Un riavvio del pod scarta ogni lavoro ancora in attesa in memoria; il suo GET risponde allora 404 - reinviate la richiesta originale.

Rifiuti

Un documento viene rifiutato per intero, prima di qualsiasi codifica, quando corrisponde a uno di questi casi; ciascuno ha il proprio messaggio 400:

Errori

# 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

Comprimi molte immagini in un'unica richiesta (solo modalità archiviata). Invia multipart/form-data con una parte file per ogni immagine; widths, formats, target e async si applicano a tutte le parti.

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

Uno slot per ogni immagine in input, in ordine. Un'immagine non valida fa fallire solo il proprio slot, non l'intero batch. Con async=1 la risposta è 202 e ogni slot è un manifest in sospeso (i suoi URL rispondono 202 finché non è codificato). Ogni immagine conta come un'unità di quota mensile; l'intero batch conta come una sola unità di rate limit. Limiti: al massimo PATU_BATCH_MAX (20) parti e una dimensione totale del payload limitata per richiesta.

GET /v1/asset/{id}

Recupera un asset archiviato tramite negoziazione del contenuto. La risposta include ETag, Vary: Accept e un Cache-Control cacheable.

La negoziazione segue l'intestazione Accept (RFC 9110, incluse le esclusioni q=0): Accept: image/jpeg restituisce JPEG, image/avif;q=0 salta AVIF, e */* o l'assenza di intestazione restituisce il migliore (AVIF). Per un controllo deterministico del formato indipendente dal client, usa gli URL espliciti {width}.{ext} (ad es. nei tag <source type>).

Altri endpoint

Limiti e backpressure

I limiti per chiave impediscono a un singolo tenant di saturare il servizio. I valori sottostanti sono quelli del piano Free; i piani a pagamento li aumentano. Rispetta Retry-After e ti regolerai in modo ottimale.

Entrambe le finestre di quota si azzerano alle 00:00 UTC (quella giornaliera ogni notte, quella mensile il giorno 1). Una richiesta rifiutata con 429 o 413 non conta ai fini della quota. Un 503 significa che gli encoder sono momentaneamente saturi, non che la richiesta fosse errata: attendi Retry-After secondi e reinvia. Gli hit di cache e i reinvii di immagini già archiviate non sono mai soggetti a rate limit da parte dell'encoder. widths non viene mai ingrandita oltre la larghezza sorgente, quindi una richiesta per una larghezza maggiore dell'originale restituisce invece la larghezza originale.

Errori

I corpi di errore sono in JSON: {"error": "..."}.