V1 e V2: convertire file o leggere il web#

L'API EnConvert ha due metà. V1 (/v1/convert/...) trasforma un file o un URL nel formato che indichi tu; V2 (/v2/...) legge una pagina web live e restituisce dati che un agente può usare. Una sola chiave copre entrambe le metà su un unico URL base, ed entrambe addebitano lo stesso contatore.

La regola di decisione#

Se sai già quale formato di output vuoi, è V1. Se vuoi sapere cosa c'è su una pagina, è V2.

Il caso scomodo: url-to-markdown (V1) e perceive (V2) si sovrappongono. Usa V1 quando vuoi un solo file Markdown e nient'altro. Usa V2 quando vuoi anche lo screenshot, i link, i metadati della pagina oppure l'opzione di ricevere i byte in streaming inline.

V1: conversione deterministica#

Invii dei byte oppure un URL, e l'endpoint che chiami è il formato di destinazione. POST /v1/convert/png-to-webp restituisce WebP. Nulla decide niente al posto tuo.

Ci sono 49 endpoint di conversione a destinazione singola distribuiti su quattro famiglie, più due crawler di siti web che percorrono un intero sito e restituiscono uno ZIP, quindi 51 route in tutto.

Di questi, website-to-pdf e website-to-screenshot sono i due crawler: individuano le pagine sotto un dominio e rispondono sempre in modo asincrono con 202 e uno ZIP. Ogni altro endpoint converte un input in un output. La mappa completa da input a output è nella matrice di conversione.

Una chiamata V1 ha questo aspetto:

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/pricing"}'

{
    "presigned_url": "https://spaces.example.com/...signed...",
    "object_key": "env/files/{project_id}/url-to-pdf/example_20260404_123456789.pdf",
    "filename": "example_20260404_123456789.pdf",
    "file_size": 123456,
    "conversion_time_seconds": 12.5
}

Imposta direct_download=true su una richiesta sincrona con un singolo URL e il corpo della risposta è il PDF stesso invece di quel JSON.

V2: leggere il web live#

V2 renderizza una pagina in un vero Chrome headless (JavaScript eseguito, contenuti lazy caricati) e restituisce quello che c'è sopra: Markdown, HTML pulito o raw, uno screenshot, un PDF, l'inventario di link e immagini, i dati strutturati della pagina oppure chunk pronti per il RAG. Più che indicare un formato di output, indichi gli output che vuoi da un unico render.

Ecco la chiamata minima utile. Invia un URL a /v2/perceive e ricevi indietro Markdown pulito e i metadati strutturati della pagina:

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "outputs": ["markdown", "structured"]
  }'

La risposta include un URL di download pre-firmato per il Markdown e il blocco strutturato inline:

{
    "operation_id": "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
    "status": "completed",
    "url_final": "https://example.com/pricing",
    "render_quality": 0.93,
    "outputs": {
        "markdown": {
            "url": "https://spaces.example.com/...signed...",
            "size_bytes": 8421,
            "expires_in": 900
        }
    },
    "structured": {
        "metadata": {"title": "Pricing"}
    }
}

Invii JSON e ricevi un risultato inline oppure un URL firmato a breve scadenza verso un artefatto. Questa è la forma di ogni endpoint V2.

Cosa è live oggi#

Tutti e sei gli endpoint V2 sono chiamabili. Due di questi sono disponibili in generale: Perceive e Ingest.

Cosa condividono le due metà#

V2 è additivo. Gli endpoint V1 restano invariati e non sono toccati da nulla di tutto questo. Non c'è alcuna migrazione: aggiungi V2 accanto a V1 quando ti serve.

Una sola chiave. Una chiave privata sk_ nell'header X-API-Key, oppure una chiave pubblica pk_ scambiata con un token bearer JWT, funziona in modo identico su V1 e V2. Consulta autenticazione per il flusso completo, incluso il domain locking e il refresh dei token.

Una sola allowlist. Ogni API key porta con sé un elenco di endpoint consentiti. Un percorso V2 non presente nell'elenco della chiave viene rifiutato con 403, esattamente come accadrebbe per un percorso V1.

Un solo contatore. Le conversioni V1 e le operazioni V2 addebitano lo stesso contatore mensile di ops. Una op è un'unità di lavoro: una conversione, un URL sottoposto a perceive, una pagina ingerita. Non ci sono moltiplicatori per endpoint, quindi un render costoso costa la stessa op di una conversione da JSON a YAML. Le quote dei piani sono su rate limit e quote.

Un solo meccanismo di consegna. L'output file di entrambe le metà viene caricato su storage e restituito come URL pre-firmato che scade dopo 15 minuti (expires_in: 900). Rifai il fetch dell'operazione, del job o del batch per ottenere un nuovo set; la ri-firma non rirenderizza nulla e non costa ops. Dettagli su URL firmati.

Scelte di design valide in tutto V2#

Imparale una volta e valgono per tutta la V2.

Un unico render tramite un browser condiviso. Perceive e Ingest eseguono il render tramite lo stesso singleton headless Chrome e la stessa pipeline di cattura dietro l'endpoint V1 url-to-pdf. I banner dei cookie vengono chiusi, la pagina viene scrollata per attivare i contenuti lazy e alle immagini viene dato il tempo di caricarsi.

Protezione SSRF su ogni URL. Prima di ogni fetch o render, ogni URL viene controllato su schema, credenziali incorporate, hostname bloccati e IP risolto. Un URL che si risolve in un indirizzo privato, loopback, link-local o di cloud metadata viene rifiutato con 400. Questo vale allo stesso modo per i seed e per i link crawlati.

Punteggio di qualità del render. Ogni render porta un punteggio render_quality da 0.0 a 1.0. Un punteggio basso segnala una pagina che sembra bloccata da una protezione anti-bot o nascosta dietro un login, così puoi distinguere una cattura reale da una pagina di verifica.

Credenziali solo dove sono al sicuro. Perceive accetta auth, cookies e headers personalizzati per le pagine dietro login. Ingest deliberatamente no, perché i suoi job sono durevoli e riprendibili e nulla di segreto deve essere salvato per una ripresa. Hai bisogno di credenziali per una pagina in un set di ingest? Renderizzala invece tramite perceive.

I parametri riservati lo dicono. Dove un parametro è accettato dallo schema ma non ancora collegato, V2 te lo dice invece di ignorarlo silenziosamente. proxy_url, geolocation e action_chain di perceive oggi restituiscono 422; i nomi di estrazione prices, contacts e technologies finiscono in warnings e vengono scartati.

Da dove partire#

• Convertire un file o un URL: gli endpoint Convert.
• Leggere una pagina: l'endpoint perceive.
• Costruire un corpus RAG da un sito: l'endpoint ingest.
• Provare gli endpoint in beta privata: In arrivo.

Se non hai ancora fatto la prima chiamata, la guida rapida ti accompagna nell'ottenere una chiave e nell'eseguire una richiesta end to end.

Domande frequenti#

Mi serve un'API key separata per V2?#

No. Una sola chiave copre entrambe le metà. Una chiave privata sk_ nell'header X-API-Key, oppure un JWT generato da una chiave pubblica pk_, autentica V1 e V2 in modo identico, nei limiti dell'elenco di endpoint consentiti della chiave.

V2 sostituisce V1?#

No. V2 è additivo e V1 resta invariato. Se vuoi un formato di output preciso a partire da un file o da un URL, V1 è ancora la chiamata giusta, e continuerà a esserlo.

Come viene conteggiato l'utilizzo tra V1 e V2?#

Entrambe le metà addebitano un unico contatore mensile di ops, e una op è un'unità di lavoro: una conversione V1, un URL sottoposto a perceive, una pagina ingerita. Non c'è alcuna ponderazione per endpoint. Consulta rate limit e quote.

Quali endpoint V2 posso chiamare oggi?#

Tutti e sei. Perceive e Ingest sono disponibili in generale. Distill, Lookup, Watch e Discover sono in beta privata: chiamabili con la tua chiave abituale, documentati in In arrivo, liberi di cambiare forma senza preavviso, e Watch richiede in più un piano a pagamento.