Distill

POST /v2/distill estrae dati strutturati da uno o più URL per conformarli a uno schema che fornisci tu. Funziona con un motore a due passaggi: prima un passaggio CSS gratuito (lo JsonCssExtractionStrategy di Crawl4AI guidato dai tuoi selettori), poi — solo per i campi che il passaggio CSS ha lasciato vuoti — un passaggio LLM limitato sul claude-haiku-4-5 di Anthropic. Il campo data della risposta è garantito tornare esattamente nella forma che hai richiesto. È la risposta di EnConvert a Firecrawl /extract.

Ecco la chiamata utile più piccola. Invia un URL e uno schema flat {field: description}, e ottieni indietro i campi estratti:

curl -X POST https://api.enconvert.com/v2/distill \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/product/widget"],
    "schema": {
      "name": "the product name",
      "price": "the listed price",
      "in_stock": "whether it is in stock"
    }
  }'

La risposta riporta un risultato per URL, i data estratti e quale tier li ha prodotti:

{
    "operation_id": "dst_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
    "total": 1,
    "completed": 1,
    "failed": 0,
    "results": [
        {
            "url": "https://example.com/product/widget",
            "url_final": "https://example.com/product/widget",
            "status": "completed",
            "data": {
                "name": "Widget Pro",
                "price": "$49.00",
                "in_stock": "yes"
            },
            "extraction_tier": "llm",
            "fields_from_css": 0,
            "fields_from_llm": 3,
            "render_quality": 0.91,
            "tokens": {"input": 4120, "output": 38},
            "cost_cents": 0.45,
            "warnings": []
        }
    ],
    "total_cost_cents": 0.45,
    "warnings": []
}

Vale la pena segnalarlo subito. /v2/distill è un endpoint V2 con un suo contatore di quota, distill_operations, dove una operazione equivale a un URL distillato. I piani di conversione V1 non includono operazioni di distill — ti serve un piano che includa V2 per chiamarlo. Distill fattura solo gli URL che si completano, quindi un fallimento di render di EnConvert non ti costa mai un'unità. Vedi la panoramica della web intelligence V2 per capire come i contatori si relazionano, e la pagina dei prezzi per le allocazioni per tier.

Endpoints

Content-Type: application/json.

A differenza di perceive, distill è un singolo endpoint sincrono — non c'è un GET separato per il re-fetch né un percorso batch asincrono. Ogni URL viene renderizzato in sequenza attraverso il singleton Chrome headless condiviso e l'intero set di risultati torna in un'unica risposta.

Authentication

Autenticati con una chiave privata nell'header X-API-Key per le chiamate server-to-server. È il percorso usato dagli esempi qui sotto.

X-API-Key: sk_live_your_private_key

Funzionano anche le chiavi pubbliche con un token bearer JWT, usando lo stesso flusso di ogni altro endpoint — genera un token con la tua chiave pk_, poi invialo come Authorization: Bearer <token>. Il flusso completo, incluso il domain locking e il refresh del token, è ne la guida all'autenticazione.

Ogni chiave API porta con sé un'allowlist di endpoint consentiti. Se /v2/distill non è nella lista della chiave, la richiesta viene rifiutata con 403.

Come funziona distill

Una richiesta distilla una lista di URL contro un unico schema. Il flusso è lo stesso per ogni URL:

1. Risolvi la lista di URL. Con urls, la lista è esattamente quella che hai inviato (deduplicata, con l'ordine preservato). Con discover_from, distill esegue prima discover sull'URL seed — analizzando la sitemap, facendo crawling, o entrambi — poi distilla gli URL scoperti fino a max_pages.
2. Render. Ogni URL viene renderizzato una volta in Chrome headless attraverso la stessa pipeline di cattura che alimenta perceive. Il render viene sottoposto a screening SSRF e, se respect_robots=true, verificato contro il robots.txt del sito. Nessun artefatto viene caricato in storage — distill ha bisogno solo del DOM renderizzato.
3. Passaggio 1 — CSS (gratuito). Se hai fornito un css_schema, l'estrattore CSS gira sull'HTML renderizzato e riempie ogni campo indirizzabile via selettore a costo LLM zero. Questo passaggio è limitato a 10 secondi; in caso di timeout l'URL prosegue verso il passaggio LLM con un warning.
4. Passaggio 2 — LLM (limitato, solo quando serve). Distill raccoglie i campi dello schema che il passaggio CSS ha lasciato mancanti o vuoti e fa escalation solo di quei campi verso claude-haiku-4-5, sotto rigidi tetti di budget per chiamata e per periodo. Se il tuo piano non ha un tier LLM, la pagina è stata segnalata come bloccata, o si raggiunge un tetto di budget, il passaggio LLM viene saltato e i campi mancanti tornano come null con un warning.
5. Normalizza. Il risultato unito viene rimodellato esattamente sulle chiavi del tuo schema — gli scalari mancanti diventano null, gli array mancanti diventano [], e qualsiasi chiave extra viene scartata. La garanzia sulla forma regge a prescindere da ciò che hanno prodotto il CSS o l'LLM.

Il contatore di quota si incrementa di uno solo dopo che un URL si completa. I fallimenti di render (rifiuto SSRF, blocco robots, un render andato in crash) producono una riga di risultato failed e non costano quota.

Parametri della richiesta

Devi fornire esattamente uno tra urls o discover_from, più uno schema. Inviare entrambi, o nessuno, è un 422.

Sorgente — URL espliciti

Sorgente — discover poi distill

Schema (obbligatorio)

Lo schema è il contratto. Se invii un oggetto JSON-Schema, distill ne legge le properties; se invii una mappa flat, ogni chiave dà il nome a un campo e ogni valore è la descrizione passata all'LLM. In entrambi i casi, data torna con esattamente le chiavi di primo livello dello schema.

CSS schema (opzionale)

Fornisci un css_schema per rispondere ai campi gratuitamente prima di qualsiasi chiamata LLM. Senza di esso, ogni campo cade direttamente al passaggio LLM.

Ogni voce in fields è un CssField:

Vale la pena segnalare: il tipo di campo computed di Crawl4AI deliberatamente non è accettato. La sua forma a espressione esegue eval sull'input del chiamante, e la sua forma callable non può attraversare un confine JSON, quindi distill enumera solo i sette tipi sicuri qui sopra.

Manopole di render

Distill renderizza solo il DOM, quindi espone un piccolo sottoinsieme delle opzioni di render di perceive.

Response

POST /v2/distill restituisce un DistillResponse:

Ogni voce in results è un DistillItemResult:

Per essere chiari: la risposta non porta URL di download firmati né artefatti memorizzati. Distill restituisce i data strutturati inline e nient'altro — se vuoi anche il Markdown della pagina, l'HTML, uno screenshot o un PDF, è per quello che esiste perceive.

Il modello di costo a due passaggi

Il passaggio CSS è gratuito. Il passaggio LLM costa, quindi distill lo innesca nel modo più ristretto possibile e lo limita da diverse direzioni.

Fa escalation solo dei campi mancanti. Dopo il passaggio CSS, distill calcola quali campi dello schema sono ancora vuoti — uno scalare tornato null/"", un array tornato vuoto, o un array i cui elementi mancano di un sotto-campo dichiarato. Solo i nomi di quei campi entrano in uno schema ridotto per la chiamata LLM, il che mantiene minimi il prompt e il costo.

Salta del tutto il passaggio LLM quando vale una qualsiasi di queste condizioni, restituendo il risultato solo-CSS con un warning invece di spendere troppo:

• Il tuo piano non ha un tier LLM (llm_extraction_enabled più un agent_model_tier diverso da none).
• Il render_quality della pagina l'ha segnalata come bloccata da protezione anti-bot.
• Il budget LLM per richiesta di questa chiamata è raggiunto, o il tetto di budget per periodo è raggiunto.

I tetti di budget sono a strati:

Nota. Il budget per periodo viene riservato atomicamente prima della chiamata e regolato sul costo reale dopo, così che chiamate concorrenti non possano collettivamente sforare il tetto. Un progetto senza una riga di periodo di utilizzo attivo fallisce in chiusura — una spesa che EnConvert non può contabilizzare è una spesa che non fa. Quando un tetto è raggiunto, i campi interessati tornano come null con un warning; la richiesta riesce comunque.

Quando il passaggio LLM gira, extraction_tier riporta llm o mixed, e tokens e cost_cents riportano quanto è costato. Quando non gira, entrambi sono zero.

Mappare i record CSS sul tuo schema

Il caso comune è una pagina di listing: una riga ripetuta, e uno schema di output con una proprietà array che contiene le righe. Dai a distill un css_schema il cui baseSelector corrisponde alla riga e i cui fields leggono le colonne, e riempie l'array gratuitamente:

curl -X POST https://api.enconvert.com/v2/distill \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/products"],
    "schema": {
      "type": "object",
      "properties": {
        "products": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {"type": "string"},
              "price": {"type": "string"},
              "sku": {"type": "string"}
            }
          }
        }
      }
    },
    "css_schema": {
      "baseSelector": ".product-card",
      "target_field": "products",
      "fields": [
        {"name": "name", "type": "text", "selector": ".title"},
        {"name": "price", "type": "text", "selector": ".price"},
        {"name": "sku", "type": "attribute",
         "selector": ".product-card", "attribute": "data-sku"}
      ]
    }
  }'

Come i record si depositano sullo schema:

• target_field impostato su una proprietà array → quella proprietà riceve la lista completa di record.
• target_field impostato su una proprietà scalare/oggetto → riceve il primo record.
• target_field omesso, lo schema ha esattamente una proprietà array → distill la deduce e riempie quella proprietà.
• Altrimenti → il primo record viene trattato come un singolo oggetto flat e le sue chiavi corrispondenti vengono sollevate al primo livello.

Se il CSS riempie l'array ma ad alcuni elementi manca un sotto-campo dichiarato — diciamo che sku è assente su metà delle card — distill fa escalation di products al passaggio LLM per colmare le lacune. È questo il fattore distintivo del modello a due passaggi rispetto a uno scraper semplice: strutturato dove può, supportato dal modello dove deve.

Esempi di codice

curl — schema flat, solo-LLM

curl -X POST https://api.enconvert.com/v2/distill \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://example.com/article"],
    "schema": {
      "headline": "the article headline",
      "author": "the author name",
      "published": "the publish date"
    }
  }'

curl — discover poi distill

curl -X POST https://api.enconvert.com/v2/distill \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "discover_from": {
      "url": "https://example.com/blog",
      "mode": "sitemap",
      "max_pages": 25
    },
    "schema": {
      "title": "the post title",
      "summary": "a one-line summary"
    }
  }'

Python

import requests

response = requests.post(
    "https://api.enconvert.com/v2/distill",
    headers={"X-API-Key": "sk_live_your_private_key"},
    json={
        "urls": ["https://example.com/product/widget"],
        "schema": {
            "name": "the product name",
            "price": "the listed price",
            "in_stock": "whether it is in stock",
        },
    },
)
response.raise_for_status()
result = response.json()

for item in result["results"]:
    if item["status"] == "completed":
        print(item["url"], "->", item["data"])
    else:
        print(item["url"], "FAILED:", item["error"])

print("total cost (cents):", result["total_cost_cents"])

Node.js

const res = await fetch("https://api.enconvert.com/v2/distill", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_live_your_private_key"
    },
    body: JSON.stringify({
        urls: ["https://example.com/product/widget"],
        schema: {
            name: "the product name",
            price: "the listed price",
            in_stock: "whether it is in stock"
        }
    })
});

const result = await res.json();

for (const item of result.results) {
    if (item.status === "completed") {
        console.log(item.url, "->", item.data);
    } else {
        console.log(item.url, "FAILED:", item.error);
    }
}

console.log("total cost (cents):", result.total_cost_cents);

Plan gating

Le operazioni di distill sono misurate sul loro contatore distill_operations, separato dalle conversioni V1 e dal contatore di perceive. Una operazione equivale a un URL distillato, e vengono contati solo gli URL che si completano. I piani di conversione V1 non includono quota di distill — ti serve un piano che includa V2.

Il passaggio LLM guidato dallo schema (claude-haiku-4-5) è un ulteriore gate di piano: gira solo quando il tuo piano porta llm_extraction_enabled e un agent model tier diverso da none. Senza di esso, distill restituisce risultati solo-CSS e annota i campi saltati in warnings. Il budget LLM per periodo è di $5 sul tier di default e $20 su Pro e superiori.

Usare discover_from richiede inoltre il flag di piano discover_enabled — altrimenti la richiesta viene rifiutata con 402, così che un piano solo-distill non possa raggiungere discover gratuitamente instradando attraverso qui.

Le allocazioni di distill_operations per tier e i piani che includono il tier LLM si trovano su la pagina dei prezzi.

Risposte di errore

Alcune note sugli stati che vale la pena tenere chiare: un singolo URL il cui render è rifiutato per SSRF emerge come 400 solo quando è il seed di una richiesta discover_from; per una lista urls esplicita, un rifiuto di render per singolo URL diventa una riga di risultato failed invece di far fallire l'intera richiesta. Un tetto di budget LLM non è mai un errore — degrada a un risultato solo-CSS con un warning. Il riferimento completo dei codici di stato è ne la guida ai codici di errore.

Limiti