--- seo_title: Tutti gli Endpoint API: Perceive, Ingest, Convert | EnConvert meta_desc: Tutti gli endpoint EnConvert in un posto: Perceive legge una pagina, Ingest fa il crawl di un sito, più 51 route Convert e il contratto di richiesta condiviso. keywords: elenco endpoint api enconvert, header x-api-key, url base api enconvert, upload multipart form data api, risposta con url presigned, parametri delle richieste api, busta di risposta api, endpoint health check api, quanti endpoint di conversione ci sono --- # Endpoint dell'API EnConvert EnConvert ha tre gruppi di endpoint. Perceive legge una singola pagina web, Ingest esegue il crawl di un intero sito trasformandolo in chunk e Convert trasforma file e URL in altri formati. Condividono un URL base, un'unica API key e un'unica quota mensile di ops, quindi il contratto di richiesta più avanti vale per tutti e tre. --- ## Perceive `POST /v2/perceive` renderizza un URL una sola volta in un browser headless e restituisce tutto quello che hai richiesto da quel singolo render: Markdown, HTML pulito o raw, uno screenshot, un PDF, l'inventario di link e immagini e i dati strutturati della pagina. Cinque route in totale, incluso un endpoint batch che accetta un elenco di URL con un unico set di opzioni, limitato dal limite di batch del tuo piano. Consulta [Perceive](/it/docs/endpoints/perceive.md). ## Ingest `POST /v2/ingest` esegue il crawl di un sito e scrive ogni pagina in un unico file JSONL di chunk pronti per il RAG; `POST /v2/ingest/files` fa lo stesso per i documenti che carichi. Ingest è sempre asincrono: il POST risponde `202` con un `job_id`, e tu fai polling oppure ricevi un webhook firmato. Otto route, incluse la rotazione del secret del webhook e la riconsegna manuale. Consulta [Ingest](/it/docs/endpoints/ingest.md). ## Convert 51 endpoint di conversione, tutti nella forma `POST /v1/convert/`, raggruppati in quattro famiglie: pagine web, documenti, formati dati e immagini. Ognuno accetta un upload di file oppure un URL e scrive il risultato su storage. Consulta [Convert](/it/docs/endpoints/convert.md). ## In sviluppo Distill, Lookup, Watch e Discover sono in beta privata e non sono trattati qui. Sono descritti in [In arrivo](/it/docs/coming-soon.md), insieme alla fase a cui ciascuno appartiene. --- ## Parametri di richiesta condivisi Tutto quello che trovi in questa sezione vale per i tre gruppi. Ciò che è specifico di una singola conversione sta sulla pagina di quell'endpoint. ### URL base ``` https://api.enconvert.com ``` Ogni percorso di questa pagina è relativo a quell'host. Il gateway tiene aperta una richiesta per al massimo 300 secondi; se entro quel limite la risposta non è iniziata ricevi `504` con `{"error": "Request timeout"}`. ### Autenticazione Ogni richiesta porta uno dei due header di credenziali. Il token Bearer viene letto per primo e l'API key per seconda. Se non ne invii nessuno dei due, l'API risponde `401` con `Authentication required`. | Header | Obbligatorio | Descrizione | |--------|----------|-------------| | `X-API-Key` | Uno dei due | La tua API key. Le chiavi private iniziano con `sk_`, quelle pubbliche con `pk_`. | | `Authorization` | Uno dei due | `Bearer `, dove il token è un JWT generato da una chiave pubblica su `POST /v1/auth/token`. I token di accesso durano un'ora. | | `Content-Type` | Sì | `application/json` per i corpi JSON, `multipart/form-data` per gli upload di file. | | `X-Parent-Origin` | Solo widget | Il dominio principale che incorpora il widget, obbligatorio per lo scambio di token con chiave pubblica. |
Le chiavi private sono solo lato server. Qualsiasi richiesta che porta un header Origin presentando una chiave sk_ viene rifiutata con 403 Private API keys cannot be used from browsers. Nel codice lato client, scambia invece una chiave pubblica con un JWT.
Il modello completo delle chiavi, incluse le allowlist di domini e gli ambiti di endpoint per chiave, è su [Autenticazione](/it/docs/authentication.md). ### Tipi di contenuto Ci sono due forme di richiesta. **Corpo JSON (`application/json`)** - Ogni endpoint `/v2` tranne `POST /v2/ingest/files`. - I cinque endpoint di conversione delle pagine web. Il loro campo `url` accetta una stringa URL oppure un array di stringhe URL. **Form multipart (`multipart/form-data`)** - I 46 endpoint di conversione di file, che leggono l'upload da un campo `file`. - `POST /v2/ingest/files`, che legge un elenco di upload da un campo `files`. Gli upload vengono controllati sull'estensione del nome file e su un'analisi dei magic byte iniziali. Una discrepanza ad alta confidenza, come un file chiamato `.pdf` i cui byte sono un PNG, restituisce `400`. I formati testuali come JSON, CSV, XML, YAML, TOML, Markdown, HTML e SVG non hanno una firma di byte, quindi superano il controllo e falliscono più avanti nel convertitore se il contenuto è malformato. ### Parametri comuni | Parametro | Si applica a | Cosa fa | |-----------|------------|--------------| | `output_filename` | Endpoint convert V1 | Assegna il nome al file di output. Viene sempre aggiunto un timestamp UTC: `{output_filename}_{YYYYMMDD_HHMMSSmmm}.{ext}`. Se includi l'estensione di destinazione, viene rimossa prima, così non ottieni mai un'estensione duplicata. | | `direct_download` | Tutti gli endpoint di conversione V1, `POST /v2/perceive` | Restituisce i byte dell'artefatto come corpo della risposta invece di una busta JSON. Il valore predefinito dipende dall'endpoint: `true` per gli upload di file, `false` per gli endpoint URL con chiave privata. Consulta [URL firmati](/it/docs/concepts/signed-urls.md). | | `async_mode`, `callback_url`, `notification_email` | Endpoint URL V1 | Mettono il lavoro in coda invece di attenderlo, e ti avvisano quando termina. Consulta [Job sincroni e asincroni](/it/docs/concepts/sync-and-async.md) e [Webhook](/it/docs/guides/webhooks.md). | | `pdf_options` | Endpoint che producono PDF | Formato pagina, margini, orientamento, scala, intestazione e piè di pagina, scala di grigi. L'elenco dei campi sta sulla pagina di ciascun endpoint PDF. | Nomi di output predefiniti quando non passi `output_filename`: - **Upload di file:** derivato dal nome del file di input, quindi `report.docx` diventa `report_20260405_123456789.pdf`. - **Conversioni da URL:** derivato dal nome di dominio, quindi `example_20260405_123456789.pdf`. - **Fallback:** `output_20260405_123456789.{ext}`. ### Busta di risposta Una conversione V1 sincrona risponde `200` con la posizione del file invece del file stesso: ```json { "presigned_url": "https://spaces.example.com/...signed...", "object_key": "live/files/4127/url-to-pdf/example_20260405_123456789.pdf", "filename": "example_20260405_123456789.pdf", "file_size": 48213, "conversion_time_seconds": 2.41 } ``` Le risposte di conversione ripetono quei metadati negli header: | Header | Descrizione | |--------|-------------| | `Content-Disposition` | `inline; filename="{filename}"` | | `X-Object-Key` | Percorso di storage del file convertito | | `X-File-Size` | Dimensione del file convertito in byte | | `X-Conversion-Time` | Tempo impiegato per la conversione, in secondi | | `X-Filename` | Nome file generato | Gli endpoint V2 restituiscono le proprie buste JSON, documentate sulle rispettive pagine, ma ogni artefatto salvato all'interno di quelle buste usa un'unica forma: ```json { "url": "https://spaces.example.com/...signed...", "object_key": "live/files/4127/v2-perceive/per_3f9a..._markdown.md", "size_bytes": 8421, "content_type": "text/markdown; charset=utf-8", "expires_in": 900 } ```
Gli URL firmati vivono 15 minuti. Funzionano più di una volta all'interno di quella finestra, e interrogare di nuovo l'endpoint di stato di un job conia un URL nuovo sullo stesso oggetto. Scarica il file o copialo nel tuo storage tempestivamente.
Altro su scadenza, riutilizzo e conservazione: [URL firmati](/it/docs/concepts/signed-urls.md). ### Errori I fallimenti tornano come oggetto JSON con un campo `detail`: ```json { "detail": "Monthly operations limit reached (500/500). Upgrade your plan to continue." } ``` `413 Payload Too Large` è l'eccezione: il suo `detail` è un oggetto che porta `error`, `file_size`, `max_size`, `tier` e `key_type`. I codici di stato e i messaggi che ci stanno dietro sono su [Errori](/it/docs/reference/errors.md). I limiti di piano che generano `402`, `413` e `429` sono su [Rate limit e quote](/it/docs/reference/rate-limits.md). --- ## Endpoint di servizio | Endpoint | Metodo | Descrizione | |----------|--------|-------------| | `/health` | `GET` | Controllo di integrità. Restituisce `200` quando database, storage e browser rispondono tutti, `503` quando uno di essi non risponde. Nessuna autenticazione. | | `/v1/whoami` | `GET` | Restituisce `{"project_id": ..., "plan_slug": ...}` per la chiave privata che presenti. Una chiave pubblica o un JWT ricevono `403`. | La generazione, il refresh e la verifica dei token stanno sotto `/v1/auth/` e sono trattati su [Autenticazione](/it/docs/authentication.md). Le route di configurazione e dei token dei widget stanno sotto `/v1/widget/` e sono trattate su [Integrazioni](/it/docs/guides/integrations.md). ## Domande frequenti ### Quali endpoint accettano upload di file? I 46 endpoint di conversione di file e `POST /v2/ingest/files`. Leggono `multipart/form-data`. Tutto il resto accetta un corpo JSON, inclusi i cinque endpoint di conversione delle pagine web, che accettano una stringa `url` oppure un array di URL. ### Gli endpoint V2 usano la stessa API key degli endpoint di conversione? Sì. Una chiave, un progetto, una quota mensile. Ogni unità di lavoro costa una op, che si tratti di una conversione di file, di un URL sottoposto a perceive o di una pagina ingerita. Non ci sono contatori per endpoint né moltiplicatori di crediti. ### Come verifico se l'API è attiva? Chiama `GET /health`. Restituisce `200` quando database, storage e browser rispondono tutti e `503` quando uno di essi non risponde, e non richiede alcuna autenticazione. ### Per quanto tempo restano validi gli URL di download? 15 minuti. Un URL può essere usato più volte prima di scadere, e ripetere il polling dell'endpoint di stato di un job restituisce un URL appena firmato per lo stesso file. ### Perché una conversione restituisce un URL invece del file? Per due motivi. Una conversione grande può durare da 60 a 120 secondi, un tempo sufficiente perché un reverse proxy davanti al tuo codice rinunci a una risposta in streaming, e lo stesso risultato spesso deve essere recuperato più di una volta. Quindi i byte finiscono sullo storage e tu ricevi un URL firmato che punta a essi. Dove ti conviene un unico round trip, `direct_download` restituisce i byte inline.