V1 et V2 : convertir des fichiers ou lire le web#
L'API EnConvert a deux moitiés. La V1 (/v1/convert/...) transforme un fichier ou une URL dans le format que vous nommez ; la V2 (/v2/...) lit une page web en direct et vous rend des données qu'un agent peut utiliser. Une seule clé couvre les deux moitiés sur une même URL de base, et les deux facturent le même compteur.
La règle de décision#
Si vous connaissez déjà le format de sortie que vous voulez, c'est la V1. Si vous voulez savoir ce qu'il y a sur une page, c'est la V2.
| Ce que vous faites | Moitié | Commencez ici |
|---|---|---|
| Transformer cette URL en PDF | V1 | url-to-pdf |
| Transformer ce DOCX en PDF | V1 | Documents |
| Transformer ce JSON en YAML | V1 | Formats de données |
| Transformer ce HEIC en WebP | V1 | Images |
| Lire cette page en Markdown pour un LLM | V2 | Perceive |
| Obtenir le Markdown, une capture d'écran, les liens et les métadonnées à partir d'un seul rendu | V2 | Perceive |
| Transformer un site entier en chunks RAG | V2 | Ingest |
Le cas limite gênant : url-to-markdown (V1) et perceive (V2) se recouvrent. Utilisez la V1 quand vous voulez un fichier Markdown et rien d'autre. Utilisez la V2 quand vous voulez aussi la capture d'écran, les liens, les métadonnées de la page, ou la possibilité de récupérer les octets en ligne.
V1 : la conversion déterministe#
Vous envoyez des octets ou une URL, et l'endpoint que vous appelez est le format cible. POST /v1/convert/png-to-webp renvoie du WebP. Rien ne décide quoi que ce soit à votre place.
Il existe 49 endpoints de conversion à cible unique répartis en quatre familles, plus deux crawlers de site qui parcourent un site entier et renvoient un ZIP, soit 51 routes au total.
| Famille | Endpoints | Entrée |
|---|---|---|
| Pages web | 5 | Une URL (ou une liste d'URL) dans un corps JSON |
| Documents | 13 | Un envoi de fichier (multipart/form-data) |
| Formats de données | 11 | Un envoi de fichier (multipart/form-data) |
| Images | 22 | Un envoi de fichier (multipart/form-data) |
Parmi eux, website-to-pdf et website-to-screenshot sont les deux crawlers : ils découvrent les pages d'un domaine et répondent toujours de manière asynchrone avec 202 et un ZIP. Tous les autres endpoints convertissent une entrée en une sortie. La carte complète des entrées vers les sorties se trouve sur la matrice de conversion.
Un appel V1 ressemble à ceci :
curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
-H "X-API-Key: sk_your_private_key" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/pricing"}'
{
"presigned_url": "https://spaces.example.com/...signed...",
"object_key": "env/files/{project_id}/url-to-pdf/example_20260404_123456789.pdf",
"filename": "example_20260404_123456789.pdf",
"file_size": 123456,
"conversion_time_seconds": 12.5
}
Définissez direct_download=true sur une requête synchrone à une seule URL et le corps de la réponse est le PDF lui-même au lieu de ce JSON.
V2 : lire le web en direct#
La V2 effectue le rendu d'une page dans un vrai Chrome headless (JavaScript exécuté, contenu en chargement différé chargé) et renvoie ce qui s'y trouve : Markdown, HTML nettoyé ou brut, une capture d'écran, un PDF, l'inventaire des liens et des images, des données structurées de la page, ou des chunks prêts pour le RAG. Vous ne nommez pas tant un format de sortie que les sorties que vous voulez à partir d'un seul rendu.
Voici l'appel utile le plus simple. Envoyez une URL à /v2/perceive pour récupérer 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_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"}
}
}
Vous envoyez du JSON, vous récupérez un résultat en ligne ou une URL signée à courte durée de vie vers un artefact. C'est la forme de chaque endpoint V2.
Ce qui est en ligne aujourd'hui#
Les six endpoints V2 sont appelables. Deux d'entre eux sont en disponibilité générale : Perceive et Ingest.
| Endpoint | Statut | Ce qu'il fait |
|---|---|---|
POST /v2/perceive |
En ligne | Rend une URL une seule fois et retourne toutes les sorties demandées : Markdown, HTML nettoyé ou brut, capture d'écran, PDF, liens, images, données structurées. |
POST /v2/ingest |
En ligne | Crawle un site (ou accepte des fichiers téléversés) et produit un seul fichier JSONL de chunks prêts pour le RAG, de manière asynchrone derrière un job_id. |
| Distill | Bêta privée | Référence |
| Lookup | Bêta privée | Référence |
| Watch | Bêta privée | Référence |
| Discover | Bêta privée | Référence |
Ce que les deux moitiés partagent#
La V2 est purement additive. Les endpoints V1 restent inchangés et ne sont affectés par rien de tout cela. Il n'y a pas de migration : vous ajoutez la V2 à côté de la V1 quand vous en avez besoin.
Une seule clé. Une clé privée sk_ dans l'en-tête X-API-Key, ou une clé publique pk_ échangée contre un jeton bearer JWT, fonctionne de façon identique sur la V1 et la V2. Consultez le guide d'authentification pour le flux complet, y compris le verrouillage de domaine et le renouvellement de jeton.
Une seule liste d'autorisation. Chaque clé API porte une liste d'endpoints autorisés. Un chemin V2 absent de la liste de la clé est rejeté avec 403, exactement comme le serait un chemin V1.
Un seul compteur. Les conversions V1 et les opérations V2 facturent le même compteur mensuel d'ops. Une op est une unité de travail : une conversion, une URL perçue, une page ingérée. Il n'y a pas de multiplicateurs par endpoint, donc un rendu coûteux coûte la même op qu'une conversion de JSON vers YAML. Les allocations par plan sont sur les limites de débit et quotas.
Un seul mécanisme de livraison. Les fichiers produits par l'une ou l'autre moitié sont téléversés vers le stockage et retournés sous forme d'URL pré-signée qui expire au bout de 15 minutes (expires_in: 900). Récupérez à nouveau l'opération, le job ou le lot pour obtenir un nouveau jeu d'URLs ; re-signer ne re-rend rien et ne coûte aucune op. Détails sur les URLs signées.
Choix de conception valables sur toute la V2#
Apprenez-les une fois et ils s'appliquent à toute la V2.
Un seul rendu via un navigateur partagé. Perceive et Ingest effectuent leur rendu via le même singleton headless Chrome et le même pipeline de capture que l'endpoint V1 url-to-pdf. Les bannières de cookies sont fermées, la page est défilée pour déclencher le contenu lazy, et les images ont le temps de charger.
Protection SSRF sur chaque URL. Avant tout fetch ou rendu, chaque URL est examinée : schéma, identifiants embarqués, noms d'hôtes bloqués et IP résolue. Une URL qui résout vers une adresse privée, loopback, link-local, ou de métadonnées cloud est rejetée avec 400. Cela s'applique aussi bien aux seeds qu'aux liens crawlés.
Score de qualité de rendu. Chaque rendu porte un score render_quality de 0.0 à 1.0. Un score bas 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.
Des identifiants uniquement là où c'est sûr. Perceive accepte auth, cookies, et des headers personnalisés pour les pages derrière une connexion. Ingest, délibérément, ne les accepte pas : ses jobs sont durables et reprenables, et rien de secret ne doit être persisté pour une reprise. Besoin d'identifiants pour une page d'un ensemble ingest ? Rendez-la plutôt via perceive.
Les paramètres réservés le disent. Lorsqu'un paramètre est accepté par le schéma mais pas encore branché, la V2 vous le signale au lieu de l'ignorer silencieusement. Les paramètres proxy_url, geolocation, et action_chain de perceive retournent 422 aujourd'hui ; ses noms d'extraction prices, contacts, et technologies atterrissent dans warnings et sont abandonnés.
warnings sur chaque réponse, et attendez-vous à ce que les corps de réponse gagnent des champs avant que la V2 ne quitte la bêta. De nouveaux champs peuvent apparaître ; ceux qui sont documentés ne changeront jamais de signification silencieusement.
Par où commencer#
- Convertir un fichier ou une URL : les endpoints Convert.
- Lire une page : l'endpoint perceive.
- Construire un corpus RAG à partir d'un site : l'endpoint ingest.
- Essayer les endpoints en bêta privée : Bientôt disponible.
Si vous n'avez pas encore fait votre premier appel, le guide de démarrage rapide vous explique comment obtenir une clé et exécuter une requête de bout en bout.
Questions fréquentes#
Ai-je besoin d'une clé API distincte pour la V2 ?#
Non. Une seule clé couvre les deux moitiés. Une clé privée sk_ dans l'en-tête X-API-Key, ou un JWT généré à partir d'une clé publique pk_, authentifie la V1 et la V2 de façon identique, sous réserve de la liste d'endpoints autorisés de la clé.
La V2 remplace-t-elle la V1 ?#
Non. La V2 est additive et la V1 est inchangée. Si vous voulez un format de sortie nommé à partir d'un fichier ou d'une URL, la V1 reste le bon appel, et cela ne changera pas.
Comment l'utilisation est-elle comptabilisée entre la V1 et la V2 ?#
Les deux moitiés facturent un seul compteur mensuel d'ops, et une op est une unité de travail : une conversion V1, une URL perçue, une page ingérée. Il n'y a pas de pondération par endpoint. Voir les limites de débit et quotas.
Quels endpoints V2 puis-je appeler aujourd'hui ?#
Les six. Perceive et Ingest sont en disponibilité générale. Distill, Lookup, Watch et Discover sont en bêta privée : appelables avec votre clé habituelle, documentés dans Bientôt disponible, libres de changer de forme sans préavis, et Watch exige en plus un forfait payant.