--- seo_title: V1 e V2: convertire file o leggere il web | EnConvert meta_desc: V1 converte file e URL tra formati, V2 legge il web live per agenti e pipeline RAG. Quale delle due metà chiamare, cosa è live oggi e cosa arriva dopo. keywords: v1 e v2 api enconvert, api conversione file o web scraping, quale endpoint api usare, api web pronta per agenti ai, convertire url in markdown api, api ingestione rag, una sola api key due api, quali endpoint v2 sono disponibili --- # 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.
Live oggi: tutto V1, più tutti e sei gli endpoint V2. Perceive e Ingest sono disponibili in generale. Distill, Lookup, Watch e Discover sono chiamabili ma in beta privata, documentati in In arrivo, e le loro forme possono cambiare senza preavviso.
--- ## La regola di decisione Se sai già quale formato di output vuoi, è V1. Se vuoi sapere cosa c'è su una pagina, è V2. | Cosa stai facendo | Metà | Parti da qui | |---|---|---| | Trasformare questo URL in un PDF | V1 | [url-to-pdf](/it/docs/endpoints/convert/web-pages/url-to-pdf.md) | | Trasformare questo DOCX in un PDF | V1 | [Documenti](/it/docs/endpoints/convert/documents.md) | | Trasformare questo JSON in YAML | V1 | [Formati dati](/it/docs/endpoints/convert/data-formats.md) | | Trasformare questo HEIC in un WebP | V1 | [Immagini](/it/docs/endpoints/convert/images.md) | | Leggere questa pagina come Markdown per un LLM | V2 | [Perceive](/it/docs/endpoints/perceive.md) | | Ottenere Markdown, uno screenshot, i link e i metadati da un unico render | V2 | [Perceive](/it/docs/endpoints/perceive.md) | | Trasformare un intero sito in chunk per il RAG | V2 | [Ingest](/it/docs/endpoints/ingest.md) | 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. | Famiglia | Endpoint | Input | |---|---|---| | [Pagine web](/it/docs/endpoints/convert/web-pages.md) | 5 | Un URL (o un elenco di URL) in un corpo JSON | | [Documenti](/it/docs/endpoints/convert/documents.md) | 13 | Un upload di file (`multipart/form-data`) | | [Formati dati](/it/docs/endpoints/convert/data-formats.md) | 11 | Un upload di file (`multipart/form-data`) | | [Immagini](/it/docs/endpoints/convert/images.md) | 22 | Un upload di file (`multipart/form-data`) | 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](/it/docs/concepts/sync-and-async.md) 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](/it/docs/endpoints/convert/matrix.md). Una chiamata V1 ha questo aspetto: ```bash 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"}' ``` ```json { "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: ```bash 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: ```json { "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. | Endpoint | Stato | Cosa fa | |---|---|---| | [`POST /v2/perceive`](/it/docs/endpoints/perceive.md) | Live | Renderizza un URL una sola volta e restituisce ogni output richiesto: Markdown, HTML pulito o raw, screenshot, PDF, link, immagini, dati strutturati. | | [`POST /v2/ingest`](/it/docs/endpoints/ingest.md) | Live | Esegue il crawl di un sito (oppure accetta file caricati) ed emette un unico file JSONL di chunk pronti per il RAG, in modo asincrono dietro un `job_id`. | | Distill | Beta privata | [Riferimento](/it/docs/coming-soon/distill.md) | | Lookup | Beta privata | [Riferimento](/it/docs/coming-soon/lookup.md) | | Watch | Beta privata | [Riferimento](/it/docs/coming-soon/watch.md) | | Discover | Beta privata | [Riferimento](/it/docs/coming-soon/discover.md) |
Le ultime quattro righe sono in beta privata. Distill, Lookup, Watch e Discover rispondono a richieste reali già oggi, ma non sono annunciati, non sono disponibili in generale e le loro forme di richiesta e risposta possono cambiare senza preavviso, quindi tienili fuori da tutto ciò che è critico. Watch richiede un piano a pagamento; gli altri tre funzionano su qualsiasi piano, Founding compreso. I dettagli sono in In arrivo.
--- ## 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](/it/docs/authentication.md) 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](/it/docs/reference/rate-limits.md). **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](/it/docs/concepts/signed-urls.md). --- ## 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](/it/docs/endpoints/convert/web-pages/url-to-pdf.md). 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](/it/docs/endpoints/perceive.md). **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.
V2 è in beta. Fissa la tua integrazione ai nomi dei campi e ai codici di stato documentati, leggi warnings a ogni risposta e aspettati che i corpi delle risposte acquisiscano nuovi campi prima che V2 esca dalla beta. Potrebbero comparire nuovi campi; quelli documentati non cambieranno significato senza preavviso.
--- ## Da dove partire - **Convertire un file o un URL:** [gli endpoint Convert](/it/docs/endpoints/convert.md). - **Leggere una pagina:** [l'endpoint perceive](/it/docs/endpoints/perceive.md). - **Costruire un corpus RAG da un sito:** [l'endpoint ingest](/it/docs/endpoints/ingest.md). - **Provare gli endpoint in beta privata:** [In arrivo](/it/docs/coming-soon.md). Se non hai ancora fatto la prima chiamata, [la guida rapida](/it/docs/quickstart.md) 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](/it/docs/reference/rate-limits.md). ### 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](/it/docs/coming-soon.md), liberi di cambiare forma senza preavviso, e Watch richiede in più un piano a pagamento.