--- seo_title: Formati di file supportati ed estensioni | EnConvert meta_desc: Ogni formato accettato in input dall'API EnConvert e ogni formato prodotto, raggruppati per famiglia di conversione, più i controlli su estensione e magic byte. keywords: formati file supportati api, estensioni accettate api conversione, anything to pdf formati supportati, anything to markdown formati supportati, formati conversione immagini api, validazione magic byte file, errore 400 formato non supportato, quali estensioni accetta api enconvert --- # 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](/it/docs/endpoints/convert/matrix.md) 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. | Endpoint | Input | Output | |----------|-------|--------| | `POST /v1/convert/url-to-pdf` | Un URL, oppure un array di URL | PDF (`application/pdf`) | | `POST /v1/convert/url-to-screenshot` | Un URL, oppure un array di URL | PNG (`image/png`) | | `POST /v1/convert/url-to-markdown` | Un URL, oppure un array di URL | Markdown (`text/markdown; charset=utf-8`) | | `POST /v1/convert/website-to-pdf` | L'URL di un sito, scansionato o letto da `sitemap.xml` | ZIP di PDF | | `POST /v1/convert/website-to-screenshot` | L'URL di un sito, scansionato o letto da `sitemap.xml` | ZIP di PNG | 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. | Endpoint | Input accettato | Motore | |----------|----------------|--------| | `POST /v1/convert/html-to-pdf` | `.html`, `.htm` | WeasyPrint | | `POST /v1/convert/markdown-to-pdf` | `.md`, `.markdown` | WeasyPrint | | `POST /v1/convert/doc-to-pdf` | `.doc`, `.docx` | LibreOffice | | `POST /v1/convert/excel-to-pdf` | `.xls`, `.xlsx` | LibreOffice | | `POST /v1/convert/ppt-to-pdf` | `.ppt`, `.pptx` | LibreOffice | | `POST /v1/convert/odt-to-pdf` | `.odt` | LibreOffice | | `POST /v1/convert/ods-to-pdf` | `.ods` | LibreOffice | | `POST /v1/convert/odp-to-pdf` | `.odp` | LibreOffice | | `POST /v1/convert/ots-to-pdf` | `.ots` | LibreOffice | | `POST /v1/convert/pages-to-pdf` | `.pages` | LibreOffice | | `POST /v1/convert/numbers-to-pdf` | `.numbers` | LibreOffice | È 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. ```text .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: | Gruppo di input | Estensioni | Motore | |-------------|------------|--------| | Office, OpenDocument, iWork, RTF, CSV | `.doc` `.docx` `.xls` `.xlsx` `.ppt` `.pptx` `.odt` `.ods` `.odp` `.ots` `.pages` `.numbers` `.rtf` `.csv` | LibreOffice headless | | HTML | `.html` `.htm` `.xhtml` | WeasyPrint | | Markdown | `.md` `.markdown` `.mdown` `.mkd` | WeasyPrint | | Testo semplice | `.txt` `.text` | Racchiuso in un blocco monospace, poi WeasyPrint | | EPUB | `.epub` | Da EPUB a Markdown, poi WeasyPrint | | Immagini raster | `.png` `.jpg` `.jpeg` `.gif` `.bmp` `.tiff` `.tif` `.webp` `.heic` `.heif` | Pillow | | SVG | `.svg` | CairoSVG | | PDF | `.pdf` | Passaggio diretto con validazione | 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. ```text .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: | Gruppo di input | Estensioni | Percorso di lettura | |-------------|------------|------| | Testo e Markdown | `.txt` `.text` `.md` `.markdown` `.mdown` `.mkd` | Letti direttamente | | HTML | `.html` `.htm` `.xhtml` | Da HTML a Markdown | | Legacy e OpenDocument | `.doc` `.ppt` `.xls` `.odt` `.ods` `.odp` `.rtf` | Da LibreOffice a HTML, poi a Markdown | | Estrattori nativi | `.pdf` `.docx` `.pptx` `.xlsx` `.csv` `.epub` | Estrattore specifico per formato | Tre aspetti da mettere in conto: - **Le immagini vengono rifiutate.** `.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp`, `.tiff` e `.tif` restituiscono `400` con `Image OCR ('') 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. | Endpoint | Input accettato | Output | |----------|----------------|--------| | `POST /v1/convert/json-to-xml` | `.json` | `.xml` | | `POST /v1/convert/xml-to-json` | `.xml` | `.json` | | `POST /v1/convert/json-to-yaml` | `.json` | `.yaml` | | `POST /v1/convert/yaml-to-json` | `.yaml`, `.yml` | `.json` | | `POST /v1/convert/json-to-csv` | `.json` | `.csv` | | `POST /v1/convert/csv-to-json` | `.csv` | `.json` | | `POST /v1/convert/json-to-toml` | `.json` | `.toml` | | `POST /v1/convert/toml-to-json` | `.toml` | `.json` | | `POST /v1/convert/csv-to-xml` | `.csv` | `.xml` | | `POST /v1/convert/xml-to-csv` | `.xml` | `.csv` | | `POST /v1/convert/markdown-to-html` | `.md`, `.markdown` | `.html` | --- ## 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». | Input | Output disponibili | |-------|-------------------| | JPEG (`.jpeg`, `.jpg`) | PNG, SVG, HEIC, WebP | | PNG (`.png`) | JPEG, SVG, HEIC, WebP | | SVG (`.svg`) | JPEG, PNG, HEIC, WebP | | HEIC (`.heic`, `.heif`) | JPEG, PNG, SVG, WebP | | WebP (`.webp`) | JPEG, PNG, SVG, HEIC | | PDF (`.pdf`) | JPEG, tramite `pdf-to-jpeg` | | PNG, JPEG, WebP | Lo stesso formato, più piccolo, tramite `compress-image` | 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. | Limite | Valore | Si applica a | |-------|-------|------------| | Pixel decodificati | 40,000,000 | Ogni endpoint immagine, verificato subito dopo l'apertura dell'immagine | | Dimensione di output SVG | 10,000 px per lato | Rasterizzazione SVG (`svg-to-*`) | | Pixel di output SVG | 25,000,000 in totale | Rasterizzazione SVG (`svg-to-*`) | | Dimensione di render | 25,000,000 px per pagina | `pdf-to-jpeg`, che riduce il render per farlo rientrare | | Numero di pagine | 500 pagine | `pdf-to-jpeg` | 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. | Estensione | Content type | |-----------|--------------| | `.pdf` | `application/pdf` | | `.png` | `image/png` | | `.jpeg`, `.jpg` | `image/jpeg` | | `.heic` | `image/heic` | | `.webp` | `image/webp` | | `.svg` | `image/svg+xml` | | `.json` | `application/json` | | `.xml` | `application/xml` | | `.yaml`, `.yml` | `application/x-yaml` | | `.csv` | `text/csv` | | `.toml` | `application/toml` | | `.html` | `text/html` | | `.md` | `text/markdown; charset=utf-8` | | `.zip` | `application/zip` | 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`](/it/docs/endpoints/perceive.md) 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`](/it/docs/endpoints/ingest.md) 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: ```json { "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`: ```json { "detail": "File content does not match the 'jpeg-to-png' input type." } ```
Rinominare un file non lo converte. Chiamare photo.webp photo.png supera il filtro sull'estensione e poi fallisce il controllo dei byte con il 400 qui sopra. Invia l'estensione reale e scegli l'endpoint che le corrisponde.
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](/it/docs/guides/file-ingestion.md). --- ## Pagine correlate - La [matrice di conversione](/it/docs/endpoints/convert/matrix.md) abbina ogni input al suo output e al percorso di endpoint. - [Ingestione dei file](/it/docs/guides/file-ingestion.md) spiega come inviare i byte: caricamento multipart, un URL che l'API recupera e i tetti di dimensione che si applicano. - [Errori](/it/docs/reference/errors.md) contiene l'elenco completo dei messaggi per `400`, `413` e `415`. - [Rate limit e quote](/it/docs/reference/rate-limits.md) contiene i tetti di caricamento per piano.