Perceive

POST /v2/perceive renderizza un URL una sola volta in un browser reale e ti restituisce ogni output che richiedi da quel singolo render: Markdown, HTML ripulito o grezzo, uno screenshot, un PDF, l'inventario di link e immagini e dati strutturati (metadati della pagina, JSON-LD, intestazioni, tabelle). Sostituisce una serie di chiamate separate — url-to-markdown, url-to-screenshot, url-to-pdf, oltre al tuo scraping personalizzato — con una sola richiesta.

Ecco la chiamata utile più piccola. Invia un URL e 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 file Markdown e il blocco strutturato inline:

{
    "operation_id": "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
    "status": "completed",
    "url": "https://example.com/pricing",
    "url_final": "https://example.com/pricing",
    "content_hash": "9f2b8c1a...d4e5",
    "render_quality": 0.93,
    "cache_hit": false,
    "outputs": {
        "markdown": {
            "url": "https://spaces.example.com/...signed...",
            "object_key": "env/files/4127/v2-perceive/per_3f9a..._markdown.md",
            "size_bytes": 8421,
            "content_type": "text/markdown; charset=utf-8",
            "expires_in": 900
        }
    },
    "structured": {
        "metadata": {
            "title": "Pricing",
            "description": "Simple, usage-based pricing."
        },
        "structured_data": [
            {"@type": "Product", "name": "Pro", "offers": {"price": "99"}}
        ]
    },
    "extraction_tier": "heuristic",
    "tokens": {"input": 0, "output": 0},
    "cost_cents": 0.0,
    "duration_ms": 6230,
    "warnings": []
}

Da segnalare subito. /v2/perceive è un endpoint V2 con un proprio contatore di quota. I piani di conversione V1 non includono alcuna operazione di perceive V2 — ti serve un piano che includa V2 per chiamarlo. Vedi la pagina dei prezzi per le quote per ciascun tier.

Endpoints

Content-Type: application/json su ogni POST.

Authentication

Autentica con una chiave privata nell'header X-API-Key per le chiamate server-to-server. Questo è 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, è nella guida all'autenticazione.

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

How perceive works

Una richiesta innesca un render del browser tramite un singleton Chrome headless condiviso, poi materializza ogni output da quel render. Non paghi mai due volte per la stessa pagina in una singola chiamata.

1. Render. La pagina viene caricata in Chrome headless. I banner dei cookie vengono chiusi, la pagina viene scrollata per innescare i contenuti caricati in modalità lazy, gli header sticky vengono gestiti e alle immagini viene dato il tempo di caricarsi — la stessa pipeline di cattura che alimenta l'endpoint url-to-pdf.
2. Materialise. Dal DOM renderizzato, perceive costruisce tutto ciò che hai elencato in outputs: Markdown, HTML ripulito/grezzo, link, immagini, uno screenshot, un PDF.
3. Extract. Se hai richiesto l'output structured, perceive esegue un passaggio euristico per i metadati della pagina, JSON-LD, intestazioni e tabelle. Se invii anche uno schema e il tuo piano include il tier LLM, un modello Anthropic Claude Haiku riempie lo schema quando il passaggio euristico risulta insufficiente.
4. Score. Un punteggio di qualità del render (0.0–1.0) segnala le pagine che sembrano bloccate da protezioni anti-bot o nascoste dietro un login wall, così puoi distinguere un render reale da una pagina di challenge.

Gli output binari e di testo (Markdown, HTML, screenshot, PDF, il JSON di link e immagini) vengono caricati nello storage e restituiti come URL pre-firmati che scadono dopo 15 minuti. Il blocco structured viene restituito inline nel JSON. Recupera di nuovo qualsiasi operazione con GET /v2/perceive/{operation_id} per ottenere un nuovo set di URL firmati.

Request parameters

Core

Outputs

outputs accetta qualsiasi combinazione di questi nomi:

Rendering and waiting

Authenticated and custom requests

Structured extraction

Quando structured è in outputs, la lista extract controlla quali campi perceive estrae. Non chiedere nulla e il default sarà metadata e structured_data.

Per essere chiari: prices, contacts, e technologies sono nomi riservati. Richiederne uno oggi non genera errore — finisce nell'array warnings e viene scartato da structured.

Schema-driven extraction

Invia uno schema per estrarre campi specifici in structured.extracted:

{
    "url": "https://example.com/product/widget",
    "outputs": ["markdown", "structured"],
    "schema": {
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "price": {"type": "number"},
            "in_stock": {"type": "boolean"}
        }
    }
}

Il tier di estrazione LLM (Anthropic Claude Haiku) riempie lo schema, e si attiva solo quando valgono tutte queste condizioni: hai inviato uno schema, il tuo piano include il tier LLM (Starter e superiori), la pagina non è stata segnata come bloccata, e il passaggio euristico ha lasciato vuoti i campi dello schema. Quando viene eseguito, extraction_tier è "llm", e tokens e cost_cents riportano quanto è costata quell'estrazione; altrimenti extraction_tier è "heuristic" ed entrambi sono zero.

Nota. L'estrazione da schema ha un tetto rigido per proteggere il tuo conto: una singola estrazione ha un limite per richiesta, e la spesa giornaliera per progetto ha un limite per piano. Se viene raggiunto un limite, perceive restituisce il risultato euristico con una nota in warnings invece di spendere troppo. Su un piano senza il tier LLM, ottieni solo dati structured euristici.

Response

Sia POST /v2/perceive che GET /v2/perceive/{operation_id} restituiscono lo stesso oggetto.

Retrieve an operation

Gli URL firmati scadono dopo 15 minuti. Per scaricare un output più tardi, recupera di nuovo l'operazione — perceive ri-firma ogni URL dalle object key memorizzate. Non avviene alcun nuovo render, quindi questo non consuma quota.

curl https://api.enconvert.com/v2/perceive/per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7 \
  -H "X-API-Key: sk_live_your_private_key"

Un ID di operazione sconosciuto, o uno che appartiene a un altro progetto, restituisce 404 — l'esistenza non viene mai rivelata tra progetti.

Batch perception

POST /v2/perceive/batch percepisce una lista di URL che condividono uno stesso blocco options. Ogni URL viene renderizzato attraverso la stessa pipeline di una chiamata singola e produce la propria riga di operazione.

curl -X POST https://api.enconvert.com/v2/perceive/batch \
  -H "X-API-Key: sk_live_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/a",
      "https://example.com/b",
      "https://example.com/c"
    ],
    "options": {"outputs": ["markdown"]},
    "output_mode": "manifest"
  }'

I batch di 10 URL o meno vengono eseguiti inline e rispondono 200 con ogni risultato popolato. I batch più grandi rispondono 202 con un job_id; gli URL vengono drenati uno alla volta e tu interroghi per i risultati:

curl https://api.enconvert.com/v2/perceive/batch/{job_id} \
  -H "X-API-Key: sk_live_your_private_key"

La risposta del batch riporta l'avanzamento aggregato e contiene un risultato perceive completo per ciascun URL una volta renderizzato:

{
    "job_id": "bat_8c1a...",
    "status": "partial",
    "output_mode": "manifest",
    "total": 3,
    "completed": 2,
    "failed": 1,
    "pending": 0,
    "items": [
        {"operation_id": "per_...", "status": "completed", "url": "https://example.com/a"},
        {"operation_id": "per_...", "status": "completed", "url": "https://example.com/b"},
        {"operation_id": "per_...", "status": "failed", "url": "https://example.com/c"}
    ]
}

status è queued, processing, completed, failed, o partial (alcuni URL sono riusciti, altri sono falliti). Imposta output_mode su zip per raggruppare ogni artefatto in un unico ZIP, restituito sotto il campo zip una volta che il batch è terminato. L'accesso ai batch e la dimensione massima del batch sono limitati dal piano; vedi la pagina dei prezzi.

Caching

cache_mode controlla come perceive tratta la sua cache di risultati di 1 ora, indicizzata per il tuo progetto, l'URL, e le opzioni di richiesta che influenzano il render.

Da segnalare: un cache hit conta comunque come una operazione di perceive sulla tua quota mensile. La quota misura le operazioni, non i render del browser — la cache ti fa risparmiare tempo di render, non quota.

Code examples

curl — Markdown only

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/blog/post",
    "outputs": ["markdown"]
  }'

curl — Markdown plus structured data

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"],
    "extract": ["metadata", "structured_data", "tables"]
  }'

curl — Full outputs plus PDF

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/report",
    "outputs": ["markdown", "html_cleaned", "screenshot_full_page", "pdf"],
    "pdf_options": {"format": "A4", "print_background": true}
  }'

Python

import requests

response = requests.post(
    "https://api.enconvert.com/v2/perceive",
    headers={"X-API-Key": "sk_live_your_private_key"},
    json={
        "url": "https://example.com/pricing",
        "outputs": ["markdown", "structured"],
        "extract": ["metadata", "tables"],
    },
)
response.raise_for_status()
data = response.json()

# Download the Markdown artifact from its signed URL
markdown_url = data["outputs"]["markdown"]["url"]
markdown_text = requests.get(markdown_url).text

print(data["structured"])
print(markdown_text)

Node.js

const res = await fetch("https://api.enconvert.com/v2/perceive", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_live_your_private_key"
    },
    body: JSON.stringify({
        url: "https://example.com/pricing",
        outputs: ["markdown", "structured"],
        extract: ["metadata", "tables"]
    })
});

const data = await res.json();

// Download the Markdown artifact from its signed URL
const markdownText = await fetch(data.outputs.markdown.url).then(r => r.text());

console.log(data.structured);
console.log(markdownText);

Se chiami EnConvert da Claude, Cursor, o un altro client MCP, la stessa capacità è esposta come tool perceive_url — vedi la pagina del server MCP.

Plan gating

Le operazioni di perceive V2 sono un contatore separato dalle conversioni V1. I piani V1 non includono alcuna quota di perceive; ti serve un piano che includa V2.

L'accesso ai batch e i limiti di dimensione per batch, il supporto a basic-auth/cookie/header, e proxy_url (Business+, quando verrà rilasciato) sono limitati dal piano. I numeri attuali si trovano su la pagina dei prezzi.

Error responses

Il riferimento completo dei codici di stato è nella guida ai codici di errore.

Limits