Intelligence web V2

EnConvert V2 est une couche d'intelligence web qui s'ajoute à l'API de conversion V1 : six endpoints qui perçoivent, découvrent, recherchent, extraient, ingèrent et surveillent le web. Ils partagent un même pipeline de rendu headless-Chrome, vos clés API existantes et la même allowlist d'endpoints autorisés que V1 — et ils sont décomptés sur leurs propres compteurs de quota, de sorte qu'un appel V2 ne touche jamais à une seule conversion V1.

Voici le plus petit appel utile. Envoyez une URL à /v2/perceive, et récupérez un Markdown propre ainsi que 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 Markdown et le bloc structuré en ligne :

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

C'est la forme que partage chaque endpoint V2 : vous envoyez du JSON, et vous récupérez un résultat en ligne ou une URL signée à courte durée de vie vers un artefact. Les six endpoints diffèrent par ce qu'ils font du rendu, non par la façon dont vous les atteignez.

Les six endpoints

Chaque endpoint condense une pile d'outils distincts en un seul appel vers api.enconvert.com.

Endpoint	Ce qu'il fait	Remplace
`/v2/perceive`	Effectue le rendu d'une URL une seule fois et renvoie toutes les sorties que vous demandez — Markdown, HTML nettoyé/brut, capture d'écran, PDF, inventaire des liens et des images, données structurées.	url-to-markdown + url-to-screenshot + url-to-pdf + votre propre scraper
`/v2/discover`	Cartographie les URLs d'un site uniquement en HTTP — analyse du sitemap plus crawl, sans navigateur, sans artefact stocké.	un récupérateur de sitemap + un crawler + de la glu de dédup/filtrage
`/v2/lookup`	Lance une recherche web indépendante du fournisseur (six catégories) et effectue facultativement le rendu des top-N résultats en un seul aller-retour.	une API de recherche + l'analyse des résultats + un scraper en fan-out
`/v2/distill`	Extrait des données structurées d'une liste d'URLs pour correspondre à un schéma que vous fournissez — une passe CSS gratuite, puis une passe LLM plafonnée uniquement sur les champs manqués.	un scraper + de la glu de sélecteurs + un prompt d'extraction LLM
`/v2/ingest`	Transforme un site en chunks prêts pour le RAG et émet un fichier JSONL qui se charge dans LangChain, LlamaIndex ou un import de vector-DB.	un crawler + un scraper + votre propre chunker
`/v2/watch`	Surveille une URL à une cadence fixe, compare chaque rendu au précédent et vous notifie par webhook ou e-mail lorsqu'elle change.	un cron job + un bucket de stockage + un script de diff-et-alerte

Si vous avez utilisé Firecrawl, la correspondance est directe : /v2/lookup répond à /search, /v2/distill répond à /extract, et /v2/ingest répond à /crawl.

Comment V2 se rapporte à V1

V2 est purement additif. Les endpoints de conversion V1 — html-to-pdf, url-to-pdf, conversions d'images, conversions de documents — sont inchangés et non affectés par tout ceci. Vous ne migrez pas vers V2 ; vous l'ajoutez à côté de V1 quand vous en avez besoin.

Les deux moitiés partagent les parties qui comptent pour l'intégration :

Même authentification. Une clé privée sk_live_ dans l'en-tête X-API-Key, ou une clé publique pk_ échangée contre un token bearer JWT, fonctionne de manière identique sur V1 et V2. Voir le guide d'authentification pour le flux complet, y compris le verrouillage de domaine et le rafraîchissement de token.
Même allowlist de clés. Chaque clé API porte une liste d'endpoints autorisés. Un chemin V2 qui ne figure pas sur la liste de la clé est rejeté avec 403, exactement comme le serait un chemin V1.

Ce qu'ils ne partagent pas, c'est le compteur. Les endpoints V2 sont facturés sur leurs propres compteurs, entièrement séparés du conversions_used de V1 :

Compteur	Endpoint	Unité
`perceive_operations`	`/v2/perceive`	une opération de rendu (un cache hit compte quand même)
`lookup_queries`	`/v2/lookup`	une recherche (les pages perçues automatiquement facturent aussi `perceive_operations`)
`distill_operations`	`/v2/distill`	une URL distillée (uniquement à la complétion)
`ingest_pages`	`/v2/ingest`	une page rendue, découpée en chunks et préparée

Un appel V2 ne décrémente jamais conversions_used, et les plans de conversion réservés à V1 incluent zéro quota V2 — c'est un plan incluant V2 qui porte ces compteurs. Deux endpoints sont contrôlés par une limite de plan plutôt que par un compteur par opération : /v2/discover est uniquement HTTP et ne stocke rien, il dépend donc d'un drapeau de plan discover_enabled ; /v2/watch est borné par max_watchers — le plafond du nombre de watchers actifs qu'un projet conserve à la fois — ainsi que par la cadence de vérification minimale horaire. Les allocations par palier pour chaque compteur et limite figurent sur la page de tarification.

Choix de conception partagés à travers V2

Les six endpoints sont construits sur les mêmes primitives, de sorte qu'une décision apprise une fois vaut pour tous.

Un seul rendu via un singleton partagé. Chaque endpoint qui a besoin d'un véritable navigateur — perceive, l'auto-perceive de lookup, distill, ingest, watch — effectue son rendu via le même singleton headless Chrome et le même pipeline de capture derrière l'endpoint url-to-pdf de V1. Les bandeaux de cookies sont écartés, la page est défilée pour déclencher le contenu en lazy loading, et les images se voient accorder le temps de se charger. Discover est l'exception délibérée : il ne touche jamais au navigateur.

URLs de téléchargement pré-signées. Les artefacts binaires et texte (Markdown, HTML, captures d'écran, PDFs, le JSONL d'ingest) sont uploadés vers le stockage et renvoyés sous forme d'URL pré-signée — un lien signé à courte durée de vie vers le stockage d'objets qui ne nécessite aucune auth séparée pour télécharger. Chaque URL signée expire après 15 minutes (expires_in: 900). Re-récupérez l'opération ou le job pour en générer un nouveau jeu ; la re-signature ne refait aucun rendu et ne coûte aucun quota.

Protection SSRF sur chaque URL. Avant tout fetch ou rendu, chaque URL est filtrée — le schéma, les identifiants intégrés, les noms d'hôtes bloqués et l'IP résolue. Une URL qui se résout vers une adresse privée, loopback, link-local ou de cloud-metadata est rejetée avec 400. Cela s'applique aux seeds, aux liens crawlés, aux cibles de distill et aux cibles de watch indifféremment.

Scoring de qualité de rendu. Chaque rendu porte un score render_quality de 0.0 à 1.0. Un score faible signale une page qui semble bloquée par une protection anti-bot ou cachée derrière un mur de connexion, ce qui vous permet de distinguer une vraie capture d'une page de challenge. Watch va plus loin : un rendu en dessous du plancher de qualité 0.4 est enregistré en audit-only et ne devient jamais une baseline de diff, de sorte qu'un blocage ponctuel ne déclenche pas une fausse alerte de changement.

Sans identifiants là où ça compte. Perceive et distill acceptent auth, cookies et des headers personnalisés pour les pages derrière une connexion. Ingest et watch ne le font délibérément pas — leurs jobs sont durables et récurrents, donc rien de secret n'est jamais persisté sur disque pour une reprise ou une re-vérification. Besoin d'identifiants pour une page dans un ensemble d'ingest ? Effectuez plutôt son rendu via l'endpoint perceive.

Gestion honnête du « réservé, pas encore actif ». Lorsqu'un paramètre est accepté par le schéma mais pas encore branché, V2 vous le dit plutôt que de l'ignorer silencieusement. Les proxy_url, geolocation et action_chain de perceive renvoient 422 aujourd'hui ; ses noms d'extraction prices, contacts et technologies aboutissent dans warnings et sont abandonnés. Vous savez toujours quel bouton n'est pas prêt.

Bêta. V2 est en bêta. Épinglez votre intégration aux noms de champs et aux codes de statut documentés, lisez warnings sur chaque réponse, et attendez-vous à ce que les champs de réponse gagnent en forme — sans casser — avant que V2 ne quitte la bêta. De nouveaux champs peuvent apparaître ; ceux qui sont documentés ne changeront pas silencieusement de sens.

La suite

Pour être franc, V2 n'est pas terminé. Trois capacités sont sur la roadmap et pas encore disponibles — ne développez pas contre elles :

Automatisation de navigateur — une paire /v2/pilot et /v2/conduct pour l'interaction multi-étapes (cliquer, taper, naviguer) plutôt que le rendu en un seul coup que font les endpoints actuels. Les formes de requête et de réponse ne sont pas arrêtées, elles ne sont donc pas documentées ici.
Feedback d'extraction — un endpoint pour corriger un résultat de distill et réinjecter la correction dans les extractions futures. Nommé, pas livré.

Lorsque ces capacités arriveront, elles obtiendront leurs propres pages de référence, de la même manière que les six endpoints ci-dessus. D'ici là, les six actuels constituent toute la surface — tout ce que vous lisez ici à propos de pilot, conduct ou feedback est une note de roadmap, pas un contrat.

Quickstart

Choisissez le bon endpoint selon la forme du travail :

Effectuer le rendu d'une page → commencez par l'endpoint perceive.
Cartographier les URLs d'un site → commencez par l'endpoint discover.
Rechercher sur le web → commencez par l'endpoint lookup.
Extraire des champs structurés → commencez par l'endpoint distill.
Construire un corpus RAG → commencez par l'endpoint ingest.
Surveiller les changements → commencez par l'endpoint watch.

Si vous n'avez pas encore fait un premier appel, le guide de démarrage rapide vous accompagne pour obtenir une clé et exécuter une requête de bout en bout. Chaque page d'endpoint s'ouvre sur son propre plus petit appel curl utile, de sorte que vous pouvez en coller un et obtenir une vraie réponse en moins d'une minute.

← Image Conversions Perceive (V2) →

API Documentation