--- seo_title: REST, MCP, CLI ou SDK : lequel utiliser | EnConvert meta_desc: EnConvert expose la même API via REST, un serveur MCP, une CLI, un nœud n8n et dix SDK. Comment ces surfaces s'articulent et laquelle choisir selon le cas. keywords: rest ou serveur mcp, surfaces d'accès api, serveur mcp vs api rest, cli ou sdk, une seule clé api partout, intégrations enconvert, nœud n8n ou api, quand utiliser un sdk --- # 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/ ()` 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](/fr/dashboard) 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](/fr/docs/reference/rate-limits.md). --- ## 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 : ```bash 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 : ```bash 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 : ```json { "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](/fr/docs/guides/integrations.md)** est le point d'entrée, et couvre aussi les widgets web intégrables. - **[Installation MCP](/fr/docs/guides/integrations/mcp-setup.md)** installe `@enconvert/mcp` dans Claude Code, Cursor, Windsurf et six autres clients avec `npx @enconvert/mcp setup`. - **[n8n](/fr/docs/guides/integrations/n8n.md)** installe le node communautaire et passe en revue les six ressources. - **[CLI](/fr/docs/guides/integrations/cli.md)** couvre l'installation, `enconvert auth login`, les flags de scripting et les codes de sortie. - **[SDK](/fr/docs/guides/integrations/sdks.md)** liste les dix packages, avec une page chacun. Pour l'API elle-même, [Endpoints](/fr/docs/endpoints.md) est la référence et [Authentification](/fr/docs/authentication.md) 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.