Perceive

POST /v2/perceive rendert eine URL einmal in einem echten Browser und liefert jede Ausgabe zurück, die du aus diesem einen Render anforderst: Markdown, bereinigtes oder rohes HTML, einen Screenshot, ein PDF, das Link- und Bildverzeichnis sowie strukturierte Daten (Seitenmetadaten, JSON-LD, Überschriften, Tabellen). Es ersetzt einen Stapel separater Aufrufe — url-to-markdown, url-to-screenshot, url-to-pdf, plus dein eigenes Scraping — durch eine einzige Anfrage.

Hier ist der kleinste nützliche Aufruf. Sende eine URL, erhalte sauberes Markdown und die strukturierten Metadaten der Seite zurück:

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"]
  }'

Die Antwort enthält eine vorsignierte Download-URL für die Markdown-Datei und den strukturierten Block 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": []
}

Gleich vorweg erwähnenswert. /v2/perceive ist ein V2-Endpunkt mit eigenem Kontingentzähler. V1-Konvertierungspläne enthalten keine V2-perceive-Operationen — du brauchst einen V2-inklusiven Plan, um ihn aufzurufen. Siehe die Preisseite für die Kontingente pro Stufe.

Endpunkte

Content-Type: application/json bei jedem POST.

Authentifizierung

Authentifiziere dich mit einem privaten Schlüssel im X-API-Key-Header für Server-zu-Server-Aufrufe. Diesen Weg nutzen die Beispiele unten.

X-API-Key: sk_live_your_private_key

Öffentliche Schlüssel mit einem JWT-Bearer-Token funktionieren ebenfalls, über denselben Ablauf wie jeder andere Endpunkt — erzeuge ein Token mit deinem pk_-Schlüssel und sende es dann als Authorization: Bearer <token>. Der vollständige Ablauf, inklusive Domain-Sperre und Token-Aktualisierung, steht in der Authentifizierungs-Anleitung.

Jeder API-Schlüssel trägt eine Allowlist erlaubter Endpunkte. Wenn /v2/perceive nicht auf der Liste des Schlüssels steht, wird die Anfrage mit 403 abgelehnt.

Wie perceive funktioniert

Eine Anfrage löst einen Browser-Render über einen gemeinsam genutzten Headless-Chrome-Singleton aus und materialisiert dann jede Ausgabe aus diesem Render. Du zahlst nie zweimal für dieselbe Seite in einem einzigen Aufruf.

1. Render. Die Seite lädt in Headless Chrome. Cookie-Banner werden weggeklickt, die Seite wird gescrollt, um lazy-geladene Inhalte auszulösen, Sticky-Header werden behandelt und Bilder bekommen Zeit zum Laden — dieselbe Capture-Pipeline, die den url-to-pdf-Endpunkt antreibt.
2. Materialisieren. Aus dem gerenderten DOM baut perceive, was auch immer du in outputs aufgelistet hast: Markdown, bereinigtes/rohes HTML, Links, Bilder, einen Screenshot, ein PDF.
3. Extrahieren. Wenn du structured-Ausgabe angefordert hast, führt perceive einen heuristischen Durchlauf für Seitenmetadaten, JSON-LD, Überschriften und Tabellen durch. Wenn du außerdem ein schema sendest und dein Plan die LLM-Stufe trägt, füllt ein Anthropic Claude Haiku-Modell das Schema, wenn der heuristische Durchlauf zu kurz greift.
4. Bewerten. Ein Render-Qualitätswert (0.0–1.0) markiert Seiten, die durch Anti-Bot-Schutz blockiert oder hinter einer Login-Wand verborgen wirken, sodass du einen echten Render von einer Challenge-Seite unterscheiden kannst.

Binär- und Textausgaben (Markdown, HTML, Screenshots, PDFs, das Link- und Bild-JSON) werden in den Speicher hochgeladen und als vorsignierte URLs zurückgegeben, die nach 15 Minuten ablaufen. Der structured-Block wird inline im JSON zurückgegeben. Rufe jede Operation mit GET /v2/perceive/{operation_id} erneut ab, um einen frischen Satz signierter URLs zu erhalten.

Anfrageparameter

Kern

Outputs

outputs akzeptiert jede Kombination dieser Namen:

Rendern und Warten

Authentifizierte und benutzerdefinierte Anfragen

Structured extraction

Wenn structured in outputs steht, steuert die extract-Liste, welche Felder perceive zieht. Fordere nichts an, und es fällt auf metadata und structured_data zurück.

Um es klar zu sagen: prices, contacts und technologies sind reservierte Namen. Fordere heute einen davon an, und es gibt keinen Fehler — er landet im warnings-Array und wird aus structured entfernt.

Schema-gesteuerte Extraktion

Sende ein schema, um bestimmte Felder in structured.extracted zu ziehen:

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

Die LLM-Extraktionsstufe (Anthropic Claude Haiku) füllt das Schema und greift nur, wenn alle dieser Bedingungen zutreffen: du hast ein schema gesendet, dein Plan trägt die LLM-Stufe (Starter und aufwärts), die Seite wurde nicht als blockiert bewertet, und der heuristische Durchlauf ließ Schemafelder leer. Wenn sie läuft, ist extraction_tier gleich "llm", und tokens und cost_cents melden, was diese Extraktion gekostet hat; andernfalls ist extraction_tier gleich "heuristic" und beide sind null.

Hinweis. Schema-Extraktion ist fest gedeckelt, um deine Rechnung zu schützen: eine einzelne Extraktion ist pro Anfrage gedeckelt, und die tägliche Ausgabe pro Projekt ist durch den Plan gedeckelt. Wird ein Deckel erreicht, gibt perceive das heuristische Ergebnis mit einem Hinweis in warnings zurück, statt zu überzahlen. Auf einem Plan ohne die LLM-Stufe bekommst du nur heuristische structured-Daten.

Antwort

Sowohl POST /v2/perceive als auch GET /v2/perceive/{operation_id} geben dasselbe Objekt zurück.

Eine Operation abrufen

Signierte URLs laufen nach 15 Minuten ab. Um eine Ausgabe später herunterzuladen, rufe die Operation erneut ab — perceive signiert jede URL aus den gespeicherten Object Keys neu. Es findet kein erneuter Render statt, also verbraucht dies kein Kontingent.

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

Eine unbekannte Operations-ID oder eine, die zu einem anderen Projekt gehört, gibt 404 zurück — Existenz wird nie projektübergreifend preisgegeben.

Batch-Perception

POST /v2/perceive/batch perceived eine Liste von URLs, die einen gemeinsamen options-Block teilen. Jede URL wird durch dieselbe Pipeline wie ein Einzelaufruf gerendert und erzeugt ihre eigene Operationszeile.

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"
  }'

Batches mit 10 URLs oder weniger laufen inline und antworten mit 200, wobei jedes Ergebnis befüllt ist. Größere Batches antworten mit 202 und einer job_id; die URLs werden eine nach der anderen abgearbeitet, und du fragst die Ergebnisse ab:

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

Die Batch-Antwort meldet den aggregierten Fortschritt und trägt ein vollständiges perceive-Ergebnis pro URL, sobald gerendert:

{
    "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 ist queued, processing, completed, failed oder partial (einige URLs erfolgreich, einige fehlgeschlagen). Setze output_mode auf zip, um jedes Artefakt in ein einziges ZIP zu bündeln, das unter dem zip-Feld zurückgegeben wird, sobald der Batch fertig ist. Batch-Zugang und die maximale Batch-Größe sind plangebunden; siehe die Preisseite.

Caching

cache_mode steuert, wie perceive seinen 1-Stunden-Ergebnis-Cache behandelt, verschlüsselt nach deinem Projekt, der URL und den render-beeinflussenden Anfrageoptionen.

Erwähnenswert: ein Cache-Treffer zählt trotzdem als eine perceive-Operation gegen dein Monatskontingent. Das Kontingent misst Operationen, nicht Browser-Renders — der Cache spart dir Render-Zeit, nicht Kontingent.

Code-Beispiele

curl — Nur Markdown

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 strukturierte Daten

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 — Vollständige Ausgaben 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);

Wenn du EnConvert von Claude, Cursor oder einem anderen MCP-Client aus aufrufst, wird dieselbe Fähigkeit als das perceive_url-Tool bereitgestellt — siehe die MCP-Server-Seite.

Plan-Gating

V2-perceive-Operationen sind ein separater Zähler von V1-Konvertierungen. V1-Pläne enthalten kein perceive-Kontingent; du brauchst einen V2-inklusiven Plan.

Batch-Zugang und Größenlimits pro Batch, Basic-Auth-/Cookie-/Header- Unterstützung und proxy_url (Business+, sobald es kommt) sind durch den Plan gebunden. Aktuelle Zahlen stehen auf der Preisseite.

Fehlerantworten

Die vollständige Statuscode-Referenz steht in der Fehlercodes-Anleitung.

Limits