Esegui nella sandbox

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.

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.

Convert#

51 endpoint di conversione, tutti nella forma POST /v1/convert/<id>, 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.

In sviluppo#

Distill, Lookup, Watch e Discover sono in beta privata e non sono trattati qui. Sono descritti in In arrivo, 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 <token>`, 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.

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.
`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 e Webhook.
`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:

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

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

Errori#

I fallimenti tornano come oggetto JSON con un campo detail:

{
    "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. I limiti di piano che generano 402, 413 e 429 sono su Rate limit e quote.

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. Le route di configurazione e dei token dei widget stanno sotto /v1/widget/ e sono trattate su Integrazioni.

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.

← V1 and V2 Perceive →

API Documentation