Formati supportati#

Ogni estensione che l'API accetta e ogni formato che restituisce, con una tabella per famiglia di convertitori. Gli elenchi riportati qui sono quelli su cui il codice esegue davvero i controlli, quindi un'estensione che manca viene realmente rifiutata, non è semplicemente non documentata.

Se invece cerchi l'abbinamento (questo input, quell'output e il percorso di endpoint che li unisce), la matrice di conversione raccoglie tutti i 51 endpoint in un'unica tabella consultabile a colpo d'occhio.

Pagine web#

Cinque endpoint che accettano un URL in un corpo JSON invece di un caricamento di file.

Gli screenshot sono PNG. Non esiste un'opzione di screenshot JPEG o WebP: la chiamata di cattura è fissata a PNG nel codice. I due endpoint website-to-* sono esclusivamente asincroni e rispondono sempre 202 con un batch_id e un output_format pari a zip.

Documenti in PDF#

Undici endpoint a destinazione singola, ciascuno un caricamento multipart/form-data con il documento nel campo file. L'output è sempre un unico PDF. Il tuttofare anything-to-pdf è il dodicesimo e ha una sezione dedicata più sotto.

È il motore a decidere quali pdf_options sono ammesse. HTML e Markdown passano da WeasyPrint e accettano dimensione pagina, orientamento, margini, scala, intestazione e piè di pagina. I nove endpoint basati su LibreOffice prendono la geometria di pagina dal documento sorgente, quindi rispettano solo grayscale e restituiscono 400 se imposti esplicitamente un'opzione di geometria.

anything-to-pdf#

POST /v1/convert/anything-to-pdf accetta 36 estensioni e restituisce sempre un PDF. Funziona solo con il caricamento di file: non accetta URL.

.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

È l'estensione a scegliere il motore:

Prima di inviare un file conviene conoscere due conseguenze di questo instradamento:

• La geometria di pagina (page_size, page_width, page_height, orientation, margini, scale, header, footer) viene rispettata solo per input HTML, Markdown, testo semplice, EPUB, immagine e SVG. Se ne imposti una esplicitamente su un input office o PDF, la richiesta restituisce 400. grayscale funziona con qualsiasi input.
• Il caricamento di un PDF viene accettato e passato direttamente, dopo un controllo che i byte inizino con %PDF-. In combinazione con grayscale, questo rende l'endpoint il modo per convertire in scala di grigi un PDF esistente.

anything-to-markdown#

POST /v1/convert/anything-to-markdown accetta 22 estensioni e restituisce sempre un unico file .md in UTF-8.

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

Raggruppate in base a come vengono lette:

Tre aspetti da mettere in conto:

• Le immagini vengono rifiutate. .png, .jpg, .jpeg, .gif, .bmp, .webp, .tiff e .tif restituiscono 400 con Image OCR ('<ext>') is not yet supported on this endpoint. Su questo endpoint non c'è OCR, quindi oggi una pagina scansionata dentro un file immagine non ha alcun percorso verso il testo.
• .ots, .pages e .numbers non sono accettati qui, anche se anything-to-pdf li accetta tutti e tre. Passali prima da anything-to-pdf, dato che .pdf è nell'elenco qui sopra.
• L'output viene normalizzato prima di essere restituito: CRLF diventa LF, le sequenze di tre o più righe vuote vengono compattate e il file termina con un ritorno a capo.

L'estrazione gira sotto tetti di risorse che proteggono dai caricamenti ostili. Gli input basati su ZIP (EPUB, DOCX, XLSX, PPTX) vengono rifiutati oltre 400 MB dichiarati non compressi o 10,000 voci. Le tabelle prodotte troncano le celle a 500 caratteri e si fermano a 5,000 righe di corpo. L'estrattore PDF si ferma a 2,000 pagine e 20,000 parole per pagina.

Formati dati#

Undici endpoint, tutti caricamenti sincroni. L'estensione del file deve corrispondere all'endpoint a cui lo invii.

Immagini#

Ventidue endpoint: venti conversioni tra JPEG, PNG, SVG, HEIC e WebP (ogni coppia ordinata), più pdf-to-jpeg e compress-image. Leggi questa tabella come «in che cosa posso trasformare questo».

I nomi degli endpoint seguono la coppia: jpeg-to-png, svg-to-webp, heic-to-jpeg e così via. Nota che gli endpoint JPEG si scrivono jpeg-, non jpg-, anche se vengono accettati sia i file .jpeg sia i .jpg.

compress-image mantiene il formato di input: PNG in ingresso, PNG in uscita. Il suo target_size_kb opzionale deve valere almeno 1, e un valore inferiore restituisce 400 prima che venga consumata una op.

pdf-to-jpeg restituisce un JPEG grezzo per un PDF a pagina singola e uno ZIP da page_1.jpeg fino a page_N.jpeg per un PDF multipagina. Qualsiasi output di un convertitore che inizia con una firma ZIP viene consegnato con estensione .zip, ed è per questo che lo stesso endpoint può restituirti due content type diversi.

Tetti di pixel#

Vengono verificati separatamente dal limite di dimensione file del tuo piano, perché un file piccolo può decodificarsi in una bitmap enorme.

Le richieste SVG che sfondano un tetto di dimensione restituiscono 400 prima che venga conteggiata una op. Passando solo width o solo height, l'altro valore viene derivato dal rapporto intrinseco dell'SVG; quando quel rapporto non è leggibile, la richiesta fallisce con un 400 che li chiede entrambi.

Tipi di media in output#

I download diretti portano il tipo di media mappato a partire dall'estensione di output.

Tutto ciò che non compare in quell'elenco viene servito come application/octet-stream.

Input e output V2#

Gli endpoint di web intelligence ragionano in termini di output, non di formati di file.

POST /v2/perceive accetta un URL e restituisce uno qualsiasi di un insieme chiuso di output: markdown, html_cleaned, html_raw, screenshot, screenshot_full_page, pdf, links, images, structured. Il valore predefinito è ["markdown", "structured"]. Tutto tranne structured viene scritto nell'archiviazione e restituito come URL di download firmato; structured torna inline nel corpo della risposta.

POST /v2/ingest/files riutilizza alla lettera l'elenco di anything-to-markdown qui sopra, quindi accetta le stesse 22 estensioni e rifiuta le immagini allo stesso modo. Un singolo job accetta fino a 200 file, ciascuno con un nome lungo al massimo 255 caratteri, e l'output del job è un unico file JSONL di chunk.

Come funziona il rilevamento del formato#

I caricamenti vengono controllati due volte, e nessuno dei due controlli guarda il Content-Type della richiesta. In nessun punto dell'API esiste un'allowlist MIME per i caricamenti.

Prima, l'estensione del nome file. Se l'endpoint dichiara un elenco di formati accettati e la tua estensione non è tra questi, la richiesta fallisce subito:

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

Poi, i byte. L'API ispeziona i primi byte del caricamento e confronta ciò che trova con quanto dichiarato dall'estensione. Riconosce PNG, JPEG, GIF, WebP, HEIC e HEIF, PDF e i due tipi di contenitore office (il contenitore ZIP dietro .docx, .xlsx, .pptx, ODF, iWork ed EPUB, e il più vecchio contenitore OLE2 dietro .doc, .xls, .ppt).

I formati testuali saltano del tutto questa ispezione. JSON, CSV, XML, YAML, TOML, Markdown, HTML, SVG e testo semplice non hanno una firma affidabile, quindi la loro estensione viene presa per buona ed è il convertitore a segnalare il problema.

L'ispezione è volutamente conservativa. Rifiuta solo una mancata corrispondenza ad alta confidenza, cioè una firma che riconosce e che appartiene a un gruppo diverso da quello dichiarato dall'estensione. Il caricamento di un .png i cui byte sono un JPEG viene rifiutato. I byte che non riconosce passano. Una mancata corrispondenza restituisce 400:

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

I nomi dei file vengono riscritti, non rifiutati, lungo il percorso verso lo storage: sopravvive solo il basename, .. e i caratteri <>:"|?* vengono rimossi e gli spazi diventano underscore. Per la object key risultante vedi ingestione dei file.

Pagine correlate#

• La matrice di conversione abbina ogni input al suo output e al percorso di endpoint.
• Ingestione dei file spiega come inviare i byte: caricamento multipart, un URL che l'API recupera e i tetti di dimensione che si applicano.
• Errori contiene l'elenco completo dei messaggi per 400, 413 e 415.
• Rate limit e quote contiene i tetti di caricamento per piano.