--- seo_title: Tous les endpoints API : Perceive, Ingest, Convert | EnConvert meta_desc: Tous les endpoints EnConvert au même endroit : Perceive pour lire une page, Ingest pour crawler un site, 51 routes Convert et le contrat de requête commun. keywords: liste des endpoints api enconvert, endpoints perceive ingest convert, en-tête x-api-key api, url de base api enconvert, upload multipart form-data api, réponse en url présignée, paramètres de requête api, enveloppe de réponse api, endpoint health check api --- # 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](/fr/docs/endpoints/perceive.md). ## 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](/fr/docs/endpoints/ingest.md). ## Convert 51 endpoints de conversion, tous de la forme `POST /v1/convert/`, 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](/fr/docs/endpoints/convert.md). ## 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](/fr/docs/coming-soon.md), 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 `, 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](/fr/docs/authentication.md). ### 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](/fr/docs/concepts/signed-urls.md). | | `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](/fr/docs/concepts/sync-and-async.md) et [Webhooks](/fr/docs/guides/webhooks.md). | | `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 : ```json { "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 : ```json { "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](/fr/docs/concepts/signed-urls.md). ### Erreurs Les échecs reviennent sous forme d'objet JSON avec un champ `detail` : ```json { "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](/fr/docs/reference/errors.md). Les limites de plan qui déclenchent `402`, `413` et `429` sont sur [Limites de débit et quotas](/fr/docs/reference/rate-limits.md). --- ## 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](/fr/docs/authentication.md). Les routes de configuration et de jeton des widgets vivent sous `/v1/widget/` et sont traitées sur [Intégrations](/fr/docs/guides/integrations.md). ## 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.