Perceive

POST /v2/perceive rend une URL une seule fois dans un véritable navigateur et vous renvoie chaque sortie que vous demandez à partir de ce rendu unique : Markdown, HTML nettoyé ou brut, une capture d'écran, un PDF, l'inventaire des liens et des images, et des données structurées (métadonnées de la page, JSON-LD, titres, tableaux). Il remplace toute une pile d'appels séparés — url-to-markdown, url-to-screenshot, url-to-pdf, plus votre propre scraping — par une seule requête.

Voici l'appel utile le plus simple. Envoyez une URL, récupérez du Markdown propre et les métadonnées structurées de la page :

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 réponse contient une URL de téléchargement pré-signée pour le fichier Markdown et le bloc structuré en ligne :

{
    "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": []
}

À signaler d'emblée. /v2/perceive est un endpoint V2 avec son propre compteur de quota. Les forfaits de conversion V1 n'incluent aucune opération perceive V2 — il vous faut un forfait incluant la V2 pour l'appeler. Voir la page de tarification pour les allocations par palier.

Endpoints

Content-Type : application/json sur chaque POST.

Authentification

Authentifiez-vous avec une clé privée dans l'en-tête X-API-Key pour les appels serveur à serveur. C'est la voie utilisée par les exemples ci-dessous.

X-API-Key: sk_live_your_private_key

Les clés publiques avec un jeton bearer JWT fonctionnent aussi, en utilisant le même flux que tout autre endpoint — générez un jeton avec votre clé pk_, puis envoyez-le comme Authorization: Bearer <token>. Le flux complet, y compris le verrouillage de domaine et le rafraîchissement du jeton, se trouve dans le guide d'authentification.

Chaque clé API porte une liste d'autorisation d'endpoints. Si /v2/perceive ne figure pas dans la liste de la clé, la requête est rejetée avec un 403.

Fonctionnement de perceive

Une requête déclenche un seul rendu de navigateur via un singleton Chrome headless partagé, puis matérialise chaque sortie à partir de ce rendu. Vous ne payez jamais deux fois pour la même page dans un seul appel.

1. Rendu. La page se charge dans Chrome headless. Les bannières de cookies sont rejetées, la page est défilée pour déclencher le contenu chargé en différé, les en-têtes collants sont gérés, et les images ont le temps de se charger — le même pipeline de capture qui alimente l'endpoint url-to-pdf.
2. Matérialisation. À partir du DOM rendu, perceive construit ce que vous avez listé dans outputs : Markdown, HTML nettoyé/brut, liens, images, une capture d'écran, un PDF.
3. Extraction. Si vous avez demandé une sortie structured, perceive effectue une passe heuristique pour les métadonnées de la page, le JSON-LD, les titres et les tableaux. Si vous envoyez aussi un schema et que votre forfait porte le palier LLM, un modèle Anthropic Claude Haiku remplit le schéma lorsque la passe heuristique reste insuffisante.
4. Notation. Un score de qualité de rendu (0.0–1.0) signale les pages qui semblent bloquées par une protection anti-bot ou masquées derrière un mur de connexion, afin que vous puissiez distinguer un vrai rendu d'une page de défi.

Les sorties binaires et texte (Markdown, HTML, captures d'écran, PDF, le JSON des liens et des images) sont téléversées vers le stockage et renvoyées sous forme d'URL pré-signées qui expirent après 15 minutes. Le bloc structured est renvoyé en ligne dans le JSON. Récupérez à nouveau n'importe quelle opération avec GET /v2/perceive/{operation_id} pour obtenir un nouveau jeu d'URL signées.

Paramètres de requête

Cœur

Sorties

outputs accepte n'importe quelle combinaison de ces noms :

Rendu et attente

Requêtes authentifiées et personnalisées

Extraction structurée

Lorsque structured figure dans outputs, la liste extract contrôle quels champs perceive extrait. Ne demandez rien et il revient par défaut à metadata et structured_data.

Soyons clairs : prices, contacts et technologies sont des noms réservés. Demandez-en un aujourd'hui et cela ne provoque pas d'erreur — il atterrit dans le tableau warnings et est écarté de structured.

Extraction pilotée par schéma

Envoyez un schema pour extraire des champs spécifiques dans 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"}
        }
    }
}

Le palier d'extraction LLM (Anthropic Claude Haiku) remplit le schéma, et il ne se déclenche que lorsque toutes ces conditions sont réunies : vous avez envoyé un schema, votre forfait porte le palier LLM (Starter et au-dessus), la page n'a pas été notée comme bloquée, et la passe heuristique a laissé les champs du schéma vides. Lorsqu'il s'exécute, extraction_tier vaut "llm", et tokens et cost_cents rapportent ce que cette extraction a coûté ; sinon extraction_tier vaut "heuristic" et les deux sont à zéro.

Note. L'extraction par schéma est strictement plafonnée pour protéger votre facture : une extraction unique est plafonnée par requête, et la dépense quotidienne par projet est plafonnée selon le forfait. Si un plafond est atteint, perceive renvoie le résultat heuristique avec une note dans warnings plutôt que de dépenser au-delà. Sur un forfait sans le palier LLM, vous n'obtenez que des données structured heuristiques.

Réponse

POST /v2/perceive et GET /v2/perceive/{operation_id} renvoient tous deux le même objet.

Récupérer une opération

Les URL signées expirent après 15 minutes. Pour télécharger une sortie plus tard, récupérez à nouveau l'opération — perceive re-signe chaque URL à partir des clés d'objet stockées. Aucun nouveau rendu n'a lieu, donc cela ne consomme pas de quota.

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

Un ID d'opération inconnu, ou un qui appartient à un projet différent, renvoie un 404 — l'existence n'est jamais divulguée entre projets.

Perception par lot

POST /v2/perceive/batch perçoit une liste d'URL qui partagent un même bloc options. Chaque URL est rendue par le même pipeline qu'un appel unique et produit sa propre ligne d'opération.

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

Les lots de 10 URL ou moins s'exécutent en ligne et répondent 200 avec chaque résultat renseigné. Les lots plus grands répondent 202 avec un job_id ; les URL sont drainées une à une et vous interrogez les résultats :

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

La réponse de lot rapporte la progression agrégée et porte un résultat perceive complet par URL une fois rendue :

{
    "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 vaut queued, processing, completed, failed ou partial (certaines URL ont réussi, d'autres ont échoué). Réglez output_mode sur zip pour regrouper chaque artefact dans un seul ZIP, renvoyé sous le champ zip une fois que le lot est terminé. L'accès aux lots et la taille maximale de lot dépendent du forfait ; voir la page de tarification.

Mise en cache

cache_mode contrôle la façon dont perceive traite son cache de résultats d'une heure, clé par votre projet, l'URL et les options de requête affectant le rendu.

À signaler : un hit de cache compte tout de même comme une opération perceive sur votre quota mensuel. Le quota mesure les opérations, pas les rendus de navigateur — le cache vous fait gagner du temps de rendu, pas du quota.

Exemples de code

curl — Markdown seul

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 données structurées

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 — Sorties complètes 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);

Si vous appelez EnConvert depuis Claude, Cursor ou un autre client MCP, la même capacité est exposée sous forme d'outil perceive_url — voir la page du serveur MCP.

Restrictions par forfait

Les opérations perceive V2 sont un compteur séparé des conversions V1. Les forfaits V1 n'incluent aucun quota perceive ; il vous faut un forfait incluant la V2.

L'accès aux lots et les limites de taille par lot, la prise en charge de basic-auth/cookie/header, et proxy_url (Business+, quand il sortira) dépendent du forfait. Les chiffres actuels se trouvent sur la page de tarification.

Réponses d'erreur

La référence complète des codes de statut se trouve dans le guide des codes d'erreur.

Limites