Exécuter dans le bac à sable

Endpoints de l'API EnConvert#

EnConvert compte trois groupes d'endpoints. Perceive lit une page web, Ingest crawle un site entier en chunks, et Convert transforme des fichiers et des URL en d'autres formats. Ils partagent une même URL de base, une même clé API et un même quota mensuel d'ops : le contrat de requête décrit plus bas s'applique donc à tous.

Perceive#

POST /v2/perceive effectue le rendu d'une URL une seule fois dans un navigateur headless et renvoie tout ce que vous avez demandé à 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 de la page. Cinq routes au total, dont un endpoint par lot qui accepte une liste d'URL partageant un même ensemble d'options, plafonnée par la limite de lot de votre plan. Voir Perceive.

Ingest#

POST /v2/ingest crawle un site et écrit chaque page dans un seul fichier JSONL de chunks prêts pour le RAG ; POST /v2/ingest/files fait la même chose pour les documents que vous téléversez. Ingest est toujours asynchrone : le POST répond 202 avec un job_id, et vous l'interrogez ou vous prenez un webhook signé. Huit routes, dont la rotation du secret de webhook et la redélivrance manuelle. Voir Ingest.

Convert#

51 endpoints de conversion, tous de la forme POST /v1/convert/<id>, regroupés en quatre familles : pages web, documents, formats de données et images. Chacun prend un envoi de fichier ou une URL et écrit le résultat dans le stockage. Voir Convert.

En développement#

Distill, Lookup, Watch et Discover sont en bêta privée et ne sont pas traités ici. Ils sont décrits dans Bientôt disponible, avec la phase à laquelle chacun appartient.

Paramètres de requête communs#

Tout ce que contient cette section vaut pour les trois groupes. Ce qui est propre à une conversion donnée se trouve sur la page de cet endpoint.

URL de base#

https://api.enconvert.com

Tous les chemins de cette page sont relatifs à cet hôte. La passerelle maintient une requête ouverte pendant 300 secondes au maximum ; si aucune réponse n'a commencé d'ici là, vous obtenez 504 avec {"error": "Request timeout"}.

Authentification#

Chaque requête porte l'un des deux en-têtes d'identification. Le jeton Bearer est lu en premier, la clé API en second. N'envoyez ni l'un ni l'autre et l'API répond 401 avec Authentication required.

Header	Requis	Description
`X-API-Key`	L'un des deux	Votre clé API. Les clés privées commencent par `sk_`, les clés publiques par `pk_`.
`Authorization`	L'un des deux	`Bearer <token>`, où le jeton est un JWT généré à partir d'une clé publique via `POST /v1/auth/token`. Les jetons d'accès durent une heure.
`Content-Type`	Oui	`application/json` pour les corps JSON, `multipart/form-data` pour les envois de fichiers.
`X-Parent-Origin`	Widgets uniquement	Le domaine parent qui intègre le widget, requis pour l'échange de jeton avec une clé publique.

Les clés privées sont réservées au serveur. Toute requête qui porte un en-tête Origin tout en présentant une clé sk_ est rejetée avec 403 Private API keys cannot be used from browsers. Dans du code côté client, échangez plutôt une clé publique contre un JWT.

Le modèle complet des clés, y compris les listes de domaines autorisés et les portées d'endpoints par clé, se trouve sur Authentification.

Types de contenu#

Il existe deux formes de requête.

Corps JSON (application/json)

Tous les endpoints /v2 sauf POST /v2/ingest/files.
Les cinq endpoints de conversion de pages web. Leur champ url accepte une chaîne d'URL ou un tableau de chaînes d'URL.

Formulaire multipart (multipart/form-data)

Les 46 endpoints de conversion de fichiers, qui lisent l'envoi depuis un champ file.
POST /v2/ingest/files, qui lit une liste d'envois depuis un champ files.

Les envois sont vérifiés par l'extension du nom de fichier et par un reniflage des premiers octets (magic bytes). Une incohérence à forte confiance, par exemple un fichier nommé .pdf dont les octets sont ceux d'un PNG, renvoie 400. Les formats texte comme JSON, CSV, XML, YAML, TOML, Markdown, HTML et SVG ne portent aucune signature d'octets : ils passent le reniflage et échouent plus tard dans le convertisseur si le contenu est mal formé.

Paramètres communs#

Paramètre	S'applique à	Effet
`output_filename`	Endpoints convert V1	Nomme le fichier de sortie. Un horodatage UTC est toujours ajouté : `{output_filename}_{YYYYMMDD_HHMMSSmmm}.{ext}`. Si vous incluez l'extension cible, elle est supprimée au préalable, vous n'obtenez donc jamais d'extension en double.
`direct_download`	Tous les endpoints de conversion V1, `POST /v2/perceive`	Renvoie les octets de l'artefact dans le corps de la réponse au lieu d'une enveloppe JSON. La valeur par défaut dépend de l'endpoint : `true` pour les uploads de fichiers, `false` pour les endpoints URL avec une clé privée. Voir URLs signées.
`async_mode`, `callback_url`, `notification_email`	Endpoints URL V1	Mettent le travail en file d'attente au lieu de l'attendre, et vous préviennent quand il est terminé. Voir Tâches synchrones et asynchrones et Webhooks.
`pdf_options`	Endpoints qui produisent un PDF	Taille de page, marges, orientation, échelle, en-tête et pied de page, niveaux de gris. La liste des champs figure sur la page de chaque endpoint PDF.

Noms de sortie par défaut lorsque vous ne transmettez pas d'output_filename :

Envois de fichiers : dérivé du nom du fichier d'entrée, donc report.docx devient report_20260405_123456789.pdf.
Conversions d'URL : dérivé du nom de domaine, donc example_20260405_123456789.pdf.
Repli : output_20260405_123456789.{ext}.

Enveloppe de réponse#

Une conversion V1 synchrone répond 200 avec l'emplacement du fichier plutôt qu'avec le fichier lui-même :

{
    "presigned_url": "https://spaces.example.com/...signed...",
    "object_key": "live/files/4127/url-to-pdf/example_20260405_123456789.pdf",
    "filename": "example_20260405_123456789.pdf",
    "file_size": 48213,
    "conversion_time_seconds": 2.41
}

Les réponses de conversion reprennent ces métadonnées dans les en-têtes :

Header	Description
`Content-Disposition`	`inline; filename="{filename}"`
`X-Object-Key`	Chemin de stockage du fichier converti
`X-File-Size`	Taille du fichier converti en octets
`X-Conversion-Time`	Temps de conversion en secondes
`X-Filename`	Nom de fichier généré

Les endpoints V2 renvoient leurs propres enveloppes JSON, documentées sur leurs pages, mais chaque artefact stocké à l'intérieur de ces enveloppes suit une seule et même forme :

{
    "url": "https://spaces.example.com/...signed...",
    "object_key": "live/files/4127/v2-perceive/per_3f9a..._markdown.md",
    "size_bytes": 8421,
    "content_type": "text/markdown; charset=utf-8",
    "expires_in": 900
}

Les URL signées vivent 15 minutes. Elles fonctionnent plusieurs fois à l'intérieur de cette fenêtre, et interroger à nouveau l'endpoint de statut d'une tâche génère une nouvelle URL sur le même objet. Téléchargez le fichier ou copiez-le rapidement dans votre propre stockage.

Plus de détails sur l'expiration, la réutilisation et la rétention : URLs signées.

Erreurs#

Les échecs reviennent sous forme d'objet JSON avec un champ detail :

{
    "detail": "Monthly operations limit reached (500/500). Upgrade your plan to continue."
}

413 Payload Too Large fait exception : son detail est un objet portant error, file_size, max_size, tier et key_type. Les codes de statut et les messages qui vont avec sont sur Erreurs. Les limites de plan qui déclenchent 402, 413 et 429 sont sur Limites de débit et quotas.

Endpoints de service#

Endpoint	Méthode	Description
`/health`	`GET`	Vérification de l'état de santé. Renvoie `200` quand la base de données, le stockage et le navigateur répondent tous, `503` quand l'un d'eux ne répond pas. Aucune authentification.
`/v1/whoami`	`GET`	Renvoie `{"project_id": ..., "plan_slug": ...}` pour la clé privée que vous présentez. Une clé publique ou un JWT obtient `403`.

La génération, le renouvellement et la vérification des jetons vivent sous /v1/auth/ et sont traités sur Authentification. Les routes de configuration et de jeton des widgets vivent sous /v1/widget/ et sont traitées sur Intégrations.

Questions fréquentes#

Quels endpoints acceptent les envois de fichiers ?#

Les 46 endpoints de conversion de fichiers et POST /v2/ingest/files. Ils lisent du multipart/form-data. Tout le reste prend un corps JSON, y compris les cinq endpoints de conversion de pages web, qui acceptent une chaîne url ou un tableau d'URL.

Les endpoints V2 utilisent-ils la même clé API que les endpoints de conversion ?#

Oui. Une clé, un projet, un quota mensuel. Chaque unité de travail coûte une op, qu'il s'agisse d'une conversion de fichier, d'une URL perçue ou d'une page ingérée. Pas de compteurs par endpoint, pas de multiplicateurs de crédits.

Comment vérifier que l'API est opérationnelle ?#

Appelez GET /health. Il renvoie 200 quand la base de données, le stockage et le navigateur répondent tous et 503 quand l'un d'eux ne répond pas, et il ne nécessite aucune authentification.

Combien de temps les URL de téléchargement restent-elles valides ?#

15 minutes. Une URL peut être utilisée plusieurs fois avant d'expirer, et une nouvelle interrogation de l'endpoint de statut d'une tâche renvoie une URL fraîchement signée pour le même fichier.

Pourquoi une conversion renvoie-t-elle une URL au lieu du fichier ?#

Deux raisons. Une conversion volumineuse peut durer de 60 à 120 secondes, ce qui suffit à un reverse-proxy placé devant votre code pour abandonner une réponse en flux, et le même résultat doit souvent être récupéré plusieurs fois. Les octets partent donc dans le stockage et vous recevez une URL signée vers ceux-ci. Lorsqu'un seul aller-retour vous convient mieux, direct_download renvoie les octets en ligne.

← V1 and V2 Perceive →

API Documentation