Web intelligence V2

EnConvert V2 è un layer di web intelligence che affianca l'API di conversione V1: sei endpoint che percepiscono, scoprono, cercano, estraggono, importano e monitorano il web. Condividono un'unica pipeline di rendering headless-Chrome, le tue chiavi API esistenti e la stessa allowlist di endpoint consentiti della V1 — e vengono conteggiati su contatori di quota dedicati, quindi una chiamata V2 non tocca mai una singola conversione V1.

Ecco la chiamata utile più piccola. Invia un URL a /v2/perceive, ricevi Markdown pulito e i metadati strutturati della pagina:

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

La risposta contiene 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"}
    }
}

Questa è la forma che ogni endpoint V2 condivide: invii JSON, ricevi un risultato inline o un URL firmato a breve durata verso un artefatto. I sei endpoint differiscono in ciò che fanno con il rendering, non nel modo in cui li raggiungi.

I sei endpoint

Ogni endpoint riduce uno stack di strumenti separati in un'unica chiamata verso api.enconvert.com.

Se hai usato Firecrawl, la corrispondenza è diretta: /v2/lookup risponde a /search, /v2/distill risponde a /extract e /v2/ingest risponde a /crawl.

Come si relaziona V2 con V1

V2 è puramente additivo. Gli endpoint di conversione V1 — html-to-pdf, url-to-pdf, conversioni di immagini, conversioni di documenti — sono invariati e non influenzati da nulla di tutto questo. Non migri a V2; lo aggiungi accanto alla V1 quando ne hai bisogno.

Le due metà condividono le parti che contano per l'integrazione:

• Stessa autenticazione. Una chiave privata sk_live_ nell'header X-API-Key, o una chiave pubblica pk_ scambiata per un token bearer JWT, funziona in modo identico su V1 e V2. Vedi la guida all'autenticazione per il flusso completo, incluso il domain locking e il refresh del token.
• Stessa allowlist delle chiavi. Ogni chiave API porta con sé un elenco di endpoint consentiti. Un percorso V2 che non è nell'elenco della chiave viene rifiutato con 403, esattamente come accadrebbe per un percorso V1.

Ciò che non condividono è il contatore. Gli endpoint V2 vengono fatturati su contatori dedicati, completamente separati da conversions_used della V1:

Una chiamata V2 non decrementa mai conversions_used, e i piani di conversione solo-V1 includono zero quota V2 — è un piano con V2 incluso a portare questi contatori. Due endpoint sono regolati da un limite di piano anziché da un contatore per-operazione: /v2/discover è solo-HTTP e non memorizza nulla, quindi si appoggia a un flag di piano discover_enabled; /v2/watch è limitato da max_watchers — il tetto sul numero di watcher attivi che un progetto può tenere contemporaneamente — insieme alla cadenza minima oraria di controllo. Le allowance per-tier per ogni contatore e limite si trovano su la pagina dei prezzi.

Scelte di progettazione condivise in V2

I sei endpoint sono costruiti sulle stesse primitive, quindi una decisione che impari una volta vale per tutti.

Un rendering attraverso un singleton condiviso. Ogni endpoint che ha bisogno di un browser reale — perceive, l'auto-perceive di lookup, distill, ingest, watch — renderizza attraverso lo stesso singleton di Chrome headless e la stessa pipeline di cattura dietro l'endpoint V1 url-to-pdf. I cookie banner vengono chiusi, la pagina viene scrollata per attivare i contenuti lazy e alle immagini viene dato il tempo di caricarsi. Discover è l'eccezione deliberata: non tocca mai il browser.

URL di download pre-firmati. Gli artefatti binari e testuali (Markdown, HTML, screenshot, PDF, il JSONL di ingest) vengono caricati nello storage e restituiti come URL pre-firmato — un link firmato a breve durata verso l'object storage che non richiede autenticazione separata per il download. Ogni URL firmato scade dopo 15 minuti (expires_in: 900). Recupera di nuovo l'operazione o il job per generare un nuovo set; la ri-firma non renderizza nulla di nuovo e non costa quota.

Protezione SSRF su ogni URL. Prima di qualsiasi fetch o rendering, ogni URL viene controllato — schema, credenziali incorporate, hostname bloccati e l'IP risolto. Un URL che si risolve in un indirizzo privato, loopback, link-local o di cloud-metadata viene rifiutato con 400. Questo vale per i seed, i link sottoposti a crawl, i target di distill e i target di watch allo stesso modo.

Punteggio di qualità del rendering. Ogni rendering 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 wall, così puoi distinguere una cattura reale da una challenge page. Watch va oltre: un rendering al di sotto della soglia di qualità 0.4 viene registrato come solo-audit e non diventa mai una baseline di diff, così un blocco occasionale non fa scattare un falso alert di cambiamento.

Senza credenziali dove serve. Perceive e distill accettano auth, cookies e headers personalizzati per pagine dietro un login. Ingest e watch deliberatamente no — i loro job sono durevoli e ricorrenti, quindi nulla di segreto viene mai persistito su disco per un resume o un re-check. Hai bisogno di credenziali per una pagina in un set di ingest? Renderizzala invece attraverso l'endpoint perceive.

Gestione onesta di "riservato, non ancora attivo". 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 restituiscono oggi 422; i suoi nomi di estrazione prices, contacts e technologies finiscono in warnings e vengono scartati. Sai sempre quale manopola non è pronta.

Beta. V2 è in beta. Fissa la tua integrazione ai nomi di campo e ai codici di stato documentati, leggi warnings su ogni risposta e aspettati che i campi di risposta acquisiscano forma — ma non si rompano — prima che V2 esca dalla beta. Possono comparire nuovi campi; quelli documentati non cambieranno silenziosamente significato.

Cosa viene dopo

Per essere chiari, V2 non è finito. Tre capacità sono sulla roadmap e non ancora disponibili — non costruirci sopra:

• Automazione del browser — una coppia /v2/pilot e /v2/conduct per l'interazione multi-step (click, type, navigate) anziché il rendering single-shot che fanno gli endpoint attuali. Le forme di richiesta e risposta non sono definite, quindi non sono documentate qui.
• Feedback di estrazione — un endpoint per correggere un risultato di distill e reimmettere la correzione nelle estrazioni future. Nominato, non rilasciato.

Quando arriveranno otterranno le proprie pagine di riferimento, allo stesso modo dei sei endpoint sopra. Fino ad allora, gli attuali sei sono l'intera superficie — qualsiasi cosa tu legga qui su pilot, conduct o feedback è una nota di roadmap, non un contratto.

Quickstart

Scegli l'endpoint giusto in base alla forma del lavoro:

• Renderizzare una pagina → parti da l'endpoint perceive.
• Mappare gli URL di un sito → parti da l'endpoint discover.
• Cercare nel web → parti da l'endpoint lookup.
• Estrarre campi strutturati → parti da l'endpoint distill.
• Costruire un corpus RAG → parti da l'endpoint ingest.
• Monitorare i cambiamenti → parti da l'endpoint watch.

Se non hai ancora fatto una prima chiamata, la guida quick-start ti accompagna nell'ottenere una chiave ed eseguire una richiesta end to end. Ogni pagina di endpoint si apre con la propria chiamata curl utile più piccola, così puoi incollarne una e avere una risposta reale entro un minuto.