Une seule API, cinq façons de l'appeler#

EnConvert est une seule API HTTP à l'adresse https://api.enconvert.com. Le serveur MCP, la CLI, le nœud n8n et les dix SDK en sont des clients, pas des produits distincts. Ils appellent les mêmes endpoints avec la même clé.

REST est le substrat#

Chaque appel finit sous la même forme : une requête HTTPS vers https://api.enconvert.com portant un en-tête X-API-Key. La gateway ne peut pas savoir quel client l'a envoyée au-delà de la chaîne User-Agent, et la seule raison d'être de cette chaîne est l'attribution : chaque SDK envoie enconvert-sdk/<version> (<language>) pour que le trafic puisse être compté par langage.

Aucun client n'a d'endpoint qui lui soit propre. Il n'existe aucune opération d'API accessible via la CLI ou le serveur MCP que vous ne pourriez pas émettre avec curl et les pages de ce site.

L'inverse mérite d'être dit clairement, car c'est là que les gens sont surpris : les clients enveloppent REST à des profondeurs différentes.

La CLI est la plus large. Elle a des verbes pour les routes de conversion et pour perceive, discover, lookup, distill et ingest, plus enconvert api comme passthrough à la manière de gh, qui atteint tout ce pour quoi elle n'a pas encore de verbe.
Le serveur MCP enregistre 24 outils. Il laisse délibérément de côté les endpoints du secret de signature des webhooks (GET /v2/ingest/webhook-secret et son équivalent de rotation), parce qu'un secret de signature ne devrait pas être lisible par un modèle.
Le nœud n8n expose 6 ressources et 16 opérations, taillées pour des étapes de workflow plutôt que pour une couverture complète de l'API.
Les SDK couvrent les endpoints de conversion et les endpoints web V2 dans les dix langages.

Quand un client est plus étroit que l'API, redescendez au REST pour cet appel-là. Mélanger ne pose aucun problème. Les appels SDK et les appels HTTP écrits à la main peuvent partager un projet et une clé sans traitement particulier.

Une seule clé, toutes les surfaces#

Chaque surface s'authentifie avec la même clé API privée (sk_...), envoyée dans l'en-tête X-API-Key. Générez-en une dans le tableau de bord et elle fonctionne dans curl, dans enconvert auth login, dans une config MCP, dans un credential n8n et dans un constructeur de SDK. La faire tourner les fait toutes tourner.

La seule chose qui change, c'est l'endroit où la clé est stockée.

Surface	Où vit la clé	Variable d'environnement de surcharge
REST	Là où votre propre code garde ses secrets	--
SDK	Passée au constructeur du client	--
CLI	`credentials.toml`, mode de fichier `0600`	`ENCONVERT_API_KEY`
Serveur MCP	`~/.enconvert/config.json`, mode de fichier `600`	`ENCONVERT_API_KEY`
Nœud n8n	Le credential `enconvertApi` dans n8n	--

Ces surfaces exigent une clé privée. La CLI, le serveur MCP, le nœud n8n et les SDK attendent tous sk_.... Une clé publique pk_ sert au code navigateur qui génère un JWT de courte durée, et le credential n8n rejette purement et simplement les clés pk_. Voir Authentification.

La consommation est elle aussi partagée. Un seul quota mensuel d'ops couvre toutes les surfaces, et une opération coûte la même chose qu'elle vienne d'un programme Go ou d'un terminal. Voir Limites de débit et quotas.

Quand choisir laquelle#

Surface	Ce que c'est	À utiliser quand
REST	L'API elle-même : corps JSON et multipart sur HTTPS	Vous écrivez du code applicatif, vous ne voulez aucune dépendance, ou votre langage n'a pas de SDK
SDK	Des clients typés pour dix langages	Vous voulez l'autocomplétion sur chaque paramètre et une récupération automatique après timeout que vous n'avez pas eu à écrire
CLI	Le binaire `enconvert`, depuis Homebrew, Scoop, un script d'installation shell ou npm	Vous écrivez un script shell, vous lancez une tâche ponctuelle, ou vous travaillez en CI
Serveur MCP	`@enconvert/mcp`, un serveur stdio local pour les assistants IA	Un agent de code doit décider lui-même quand appeler l'API
Nœud n8n	`@enconvert/n8n-nodes-enconvert`, un node communautaire	Le workflow vit déjà dans n8n et vous voulez le résultat sous forme de données binary n8n

Deux de ces choix sont en général évidents. Si c'est un humain qui tape, c'est la CLI ; si c'est un modèle qui décide, c'est MCP. La question REST ou SDK est la seule qui mérite réflexion, et elle se résume à la quantité de code de réessai et d'interrogation que vous voulez maintenir.

La même lecture, de trois façons#

Lire https://example.com/pricing en Markdown, c'est une seule requête POST /v2/perceive. La voici en HTTP brut :

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

La CLI émet le même POST /v2/perceive. La commande nue n'envoie aucun outputs, elle récupère donc la valeur par défaut du serveur, à savoir du Markdown plus le bloc structuré en ligne :

enconvert perceive https://example.com/pricing

Avec MCP, vous n'écrivez pas l'appel du tout. Vous demandez à l'assistant de lire la page, il choisit l'outil perceive_url, et les arguments qui comptent ressortent ainsi :

{
  "name": "perceive_url",
  "arguments": {
    "url": "https://example.com/pricing",
    "outputs": ["markdown"]
  }
}

Même requête, même facture. Chacune des trois effectue le rendu de la page une fois et coûte une opération. Le serveur MCP fait une chose de plus : il récupère l'artefact Markdown terminé et insère le texte en ligne dans le résultat de l'outil (jusqu'à 256 KB environ), pour que l'assistant puisse lire la page sans un second téléchargement.

Où aller ensuite#

La configuration se trouve dans les guides d'intégration, une page par surface :

Intégrations est le point d'entrée, et couvre aussi les widgets web intégrables.
Installation MCP installe @enconvert/mcp dans Claude Code, Cursor, Windsurf et six autres clients avec npx @enconvert/mcp setup.
n8n installe le node communautaire et passe en revue les six ressources.
CLI couvre l'installation, enconvert auth login, les flags de scripting et les codes de sortie.
SDK liste les dix packages, avec une page chacun.

Pour l'API elle-même, Endpoints est la référence et Authentification explique les deux types de clés.

Questions fréquentes#

Le serveur MCP est-il une API différente de l'API REST ?#

Non. @enconvert/mcp est un processus stdio local qui appelle les mêmes endpoints REST publics documentés sur ce site, avec votre clé API privée. Chaque outil correspond à une requête /v1/convert/* ou /v2/* : il puise donc dans le même quota et renvoie les mêmes erreurs.

Ai-je besoin de clés API distinctes pour la CLI, MCP et mon application ?#

Non. Une seule clé privée (sk_...) les authentifie toutes, et vous pouvez réutiliser la même clé d'une surface à l'autre. Des clés distinctes restent utiles si vous voulez révoquer une surface sans toucher aux autres, par exemple une clé CI que vous pouvez faire tourner indépendamment de votre portable.

Puis-je utiliser une clé publique pk_ avec la CLI ou un SDK ?#

Non. Les clés publiques existent pour le code navigateur, où elles génèrent un JWT de courte durée au lieu d'être envoyées directement. La CLI, le serveur MCP, le nœud n8n et les SDK attendent tous une clé privée sk_..., et le credential n8n rejette une clé pk_ dès la validation.

Y a-t-il quelque chose de disponible uniquement via les SDK ou uniquement via la CLI ?#

Aucune opération d'API. Ce que les SDK ajoutent est côté client : des options typées, des téléchargements en flux vers le disque, et un repli automatique sur l'interrogation de GET /v1/convert/status/{job_id} quand une conversion longue dépasse le timeout du proxy. Vous pouvez écrire tout cela vous-même sur du REST brut.

Quelle surface utiliser dans un pipeline CI ?#

La CLI, avec ENCONVERT_API_KEY défini depuis le coffre à secrets de votre CI et --no-input pour qu'une invite ne puisse jamais bloquer l'exécution. Ses codes de sortie sont un contrat publié et stable : une conversion en échec fait donc échouer l'étape sans aucune analyse de la sortie.

← Concepts Sync and Async Jobs →

API Documentation