Une même opération, quatre clients : navigateur, curl, MCP, pdfx

Quatre clients ressemblent à quatre produits. Ils partagent un catalogue. Prenons Fusionner comme tâche concrète : combiner des PDF dans l’ordre de téléversement sans rasteriser les pages en images. Le même schéma vaut pour chaque autre outil du catalogue (compression, OCR, conversion et le reste) : un identifiant d’opération, quatre façons de l’appeler.

Navigateur

Ouvrez /fr/merge, ajoutez les fichiers dans l’ordre voulu, cliquez sur Traiter, téléchargez. Aucun compte n’est requis pour les outils du catalogue. Le bloc « Appeler depuis le code » de la page construit un curl à partir des mêmes champs que le formulaire envoie : l’interface et le contrat HTTP restent donc alignés.

Ce bloc n’est pas un texte marketing. Il est généré à partir de la définition d’outil que le portail utilise déjà pour le formulaire, ce qui explique qu’un renommage de paramètre apparaisse aux deux endroits simultanément. Si le formulaire accepte l’option sortType=byFileName, l’exemple curl peut porter le même champ.

curl / REST

curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o merged.pdf

Les appels anonymes du catalogue n’exigent aucune clé. Les clés obtenues via Développeurs donnent à l’automatisation une identité stable (et aux serveurs auto-hébergés une entrée protégée). OpenAPI se trouve à /v1/openapi.json.

Pour les tâches multi-étapes, POST /api/v1/pipeline accepte des opérations ordonnées dans un champ steps (par exemple fusionner, puis apposer un filigrane, puis compresser). Envoyez Idempotency-Key lorsque les réessais ne doivent pas réexécuter le travail ; un rejeu réussi peut revenir avec Idempotency-Replayed. Les échecs utilisent application/problem+json avec des codes stables comme rate_limited et bad_request (Erreurs pour les développeurs).

Les réponses hébergées exposent aussi X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset ; un HTTP 429 inclut Retry-After. Traitez ces en-têtes comme le budget en temps réel, et non comme un chiffre mémorisé dans un article (limitation de débit anonyme).

MCP

Les agents qui parlent Model Context Protocol se connectent à /mcp, y découvrent la fusion comme outil et l’appellent avec la même logique de clé API que REST. Documentation : MCP pour les développeurs.

MCP n’est pas un second catalogue. C’est un protocole de découverte et d’invocation des mêmes opérations que recense OpenAPI. Si une opération manque dans MCP, c’est un défaut du serveur, pas une feuille de route produit distincte. Associez MCP à /llms.txt lorsque vous voulez un index en prose des outils avant que le client se connecte.

CLI pdfx

pdf-core en local :

pdfx merge a.pdf b.pdf -o merged.pdf

Ou le même serveur que celui du portail :

pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf

Le mode local ne téléverse jamais ; le mode cloud interroge votre URL de base avec la même forme multipart que curl. La compétence d’agent de codage fournie dans dist/skills/pdf-toolbox/SKILL.md documente les mêmes formes de fusion et de pipeline, pour que les agents n’inventent pas une seconde OpenAPI.

L’OCR, via n’importe lequel de ces clients, renvoie toujours du Markdown depuis /api/v1/misc/ocr-pdf, et non une couche de texte cachée. Ce fait fait partie du contrat partagé : modifier le type de retour dans un seul client casserait la promesse d’une « même opération ». La compression reste sur /api/v1/misc/compress-pdf pour la recompression des flux ; c’est une autre opération que la fusion, accessible des quatre mêmes façons.

Pourquoi cette identité compte

Si la fusion du navigateur et celle de l’API divergeaient, les automatisations régresseraient en silence pendant que la page de démonstration semblerait intacte. Une opération, quatre accès : c’est tout l’intérêt. Le portail est un client de commodité, pas une seconde implémentation de la fusion, de la compression ou de l’OCR.

C’est aussi pourquoi il n’existe pas de version de bureau : une cinquième arborescence d’interface recréerait le problème de dérive sous un autre nom de binaire. Pour un cadre plus large : Conçu pour les agents IA, pas seulement pour les navigateurs. Pour la décision sur le bureau, voir Pourquoi nous avons renoncé à l’application de bureau. Pour installer l’API sur votre réseau, voir Auto-hébergement.