Aller au contenu principal
PPDF123

PDF123 pour les développeurs : API REST, SDK, ligne de commande et MCP

La plateforme développeur de PDF123 donne accès aux mêmes 97 outils PDF par quatre interfaces : une API REST décrite par OpenAPI, un SDK TypeScript, la ligne de commande pdfx et des serveurs MCP pour agents IA. Les appels anonymes n'exigent ni compte ni clé d'API.

Sur cette page

Comment utiliser PDF123 depuis du code ?

Les quatre interfaces appellent les mêmes opérations : une fusion donne le même résultat partout. Choisissez selon l'endroit où votre code s'exécute.

InterfaceIdéale pourInstallation ou adresseGuide
API RESTTout langage, serveurs, scripts shellhttps://pdf123.xyz/api/v1Référence de l'API
SDK TypeScriptCode Node, Bun et navigateur qui a besoin de typesnpm install @pdf123/sdkGuide du SDK
Ligne de commandeTerminaux, tâches CI, lots de fichiers locauxnpm install -g @pdf123/cliGuide de la CLI
MCPAgents IA comme Claude Code, Claude Desktop et Cursornpx -y @pdf123/mcp ou https://pdf123.xyz/mcpGuide MCP

Utilisez l'API REST si votre code n'est pas écrit en TypeScript. Utilisez le SDK s'il l'est, car les options des outils sont typées et vérifiées avant l'envoi. Utilisez la ligne de commande pour les tâches ponctuelles et les scripts shell. Utilisez MCP quand un agent IA doit choisir lui-même l'outil à lancer.

Le catalogue compte 97 outils. 58 d'entre eux ont une page sur ce site, par exemple Fusionner des PDF, Diviser un PDF et Compresser un PDF. Les autres sont des opérations du backend sans page web ; tous sont disponibles dans le SDK, la ligne de commande et MCP.

Comment lancer ma première requête ?

Fusionnez deux fichiers avec curl. La requête est un formulaire multipart avec une partie fileInput par fichier.

REST : fusionner deux PDFbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

La même fusion avec le SDK TypeScript :

SDK : fusionner deux PDFts
import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const result = await client.run("merge", {
  input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
await saveResult(result, { output: "merged.pdf" });

La même fusion avec la ligne de commande :

CLI : fusionner deux PDFbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

Comment fonctionne l'authentification ?

Les appels anonymes à l'API publique n'exigent ni compte ni clé. Envoyez une clé d'API dans l'en-tête X-API-KEY lorsque vous voulez identifier votre trafic ou appeler le point de terminaison MCP hébergé, qui exige toujours une clé.

Connectez-vous pour créer une clé dans le panneau ci-dessous, puis conservez-la en lieu sûr.

Vérification de votre session…

Appeler l'API avec une clébash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -H "X-API-KEY: <your-key>" \
  -F [email protected] -F [email protected] -o merged.pdf

Le SDK reçoit la clé dans apiKey. La ligne de commande et le serveur MCP local la lisent dans la variable d'environnement PDFX_API_KEY.

Note

Sur un serveur auto-hébergé, définissez la variable d'environnement SECURITY_CUSTOMGLOBALAPIKEY pour fixer la clé unique que le serveur accepte. Voir Auto-hébergement.

Où trouver la référence de l'API ?

L'API REST est documentée sous deux formes. Swagger UI permet d'essayer chaque point de terminaison dans le navigateur. Le document OpenAPI est la source lisible par machine pour les générateurs de clients.

Chaque opération est un POST sous l'URL de base https://pdf123.xyz/api/v1, regroupée par catégorie. Par exemple, la fusion est /general/merge-pdfs et la compression /misc/compress-pdf.

Comment enchaîner plusieurs outils dans une seule requête ?

POST /api/v1/pipeline accepte les parties fileInput et un champ steps. Ce champ est un tableau JSON d'objets contenant un op et, en option, des params. Chaque étape reçoit le résultat de l'étape précédente.

Merge, then compress, in one requestbash
curl -X POST https://pdf123.xyz/api/v1/pipeline \
  -F [email protected] -F [email protected] \
  -F 'steps=[{"op":"general/merge-pdfs"},{"op":"misc/compress-pdf"}]' \
  -o out.pdf

Comment réessayer une requête en toute sécurité ?

Envoyez un en-tête Idempotency-Key avec n'importe quelle opération. Une répétition de la même requête dans les 24 heures renvoie le premier résultat avec l'en-tête Idempotency-Replayed: true au lieu de s'exécuter à nouveau. Utiliser la même clé pour une requête différente est rejeté. Les résultats de plus de 32 MiB ne sont pas conservés : répéter une telle requête renvoie 409 et demande une nouvelle clé.

Quelles sont les limites de taille et de débit ?

LimiteValeur
Taille de fichier sur le site500 Mo par fichier
Corps d'une requête directe à l'API100 MiB, délimitation multipart comprise
Envoi par morceauxLe SDK bascule automatiquement vers l'API d'envoi au-delà de 95 Mo au total

Les réponses portent les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Une réponse de statut 429 ajoute Retry-After. Lisez ces en-têtes plutôt que de supposer un quota fixe, car un serveur auto-hébergé définit ses propres limites. L'article du blog sur la limite de taille des requêtes explique l'erreur obtenue avec un corps trop volumineux.

À quoi ressemble une erreur ?

Les échecs renvoient application/problem+json avec les champs type, title, status, detail, code, reason et hint. Raisonnez sur reason, avec code en repli. Le texte de detail est écrit pour des humains et ne contient jamais la sortie brute d'un outil. Tous les codes sont listés dans Codes d'erreur.

Code ou motifStatut HTTPSignification
bad_request400Paramètres ou corps multipart invalides
password_required400Le PDF est chiffré et aucun mot de passe n'a été envoyé
invalid_pdf400Le fichier n'est pas un PDF ou est endommagé ; essayez Réparer un PDF
page_out_of_range400Une page demandée n'existe pas
not_found404Chemin d'opération inconnu
rate_limited429Quota épuisé ; attendez la durée de Retry-After

Quels outils appeler en premier ?

Ces douze outils couvrent la plupart des requêtes. Utilisez la page de l'outil pour l'essayer dans le navigateur.

Page de l'outilPoint de terminaison de l'APICommande CLIFonction
Fusionner/general/merge-pdfspdfx mergeRéunir plusieurs PDF en un seul
Diviser/general/split-pagespdfx splitDécouper un PDF en plusieurs fichiers
Compresser/misc/compress-pdfpdfx compressRecompresser les flux du PDF pour réduire sa taille
Pivoter/general/rotate-pdfpdfx rotateChanger l'orientation des pages
Protéger/security/add-passwordpdfx protectChiffrer un PDF avec un mot de passe
Déverrouiller/security/remove-passwordpdfx unlockRetirer la protection par mot de passe
Filigrane/security/add-watermarkpdfx watermarkAjouter un filigrane de texte ou d'image
OCR/misc/ocr-pdfpdfx ocrLire un PDF numérisé et renvoyer du Markdown
PDF en Markdown/convert/pdf/markdownpdfx pdf-to-markdownConvertir un PDF en Markdown
PDF en Word/convert/pdf/wordpdfx convert-to-wordConvertir un PDF en fichier Word modifiable
Infos du document/security/get-info-on-pdfpdfx get-infoIndiquer métadonnées, autorisations, polices et structure
Réparer/misc/repairpdfx repairReconstruire la structure d'un PDF endommagé

Les points de terminaison sont relatifs à https://pdf123.xyz/api/v1. Lancez pdfx list ou ouvrez le document OpenAPI pour voir les 97 outils.

Comment utiliser PDF123 depuis un agent IA ?

Un agent peut utiliser les outils de trois façons :

  • Connecter un serveur MCP. Le guide MCP présente le serveur local @pdf123/mcp pour les fichiers de votre machine et le point de terminaison hébergé à https://pdf123.xyz/mcp.
  • Charger une skill d'agent. Les skills pour agents sont des fichiers SKILL.md pour Claude Code, Codex, Cursor et des outils similaires : une pour le catalogue et une par outil.
  • Lire l'index du site. /llms.txt liste en texte brut les outils, l'API et le point de terminaison MCP, et /site.jsonld décrit le site sous forme de données structurées.

L'article « Built for AI Agents, Not Just Browsers » du blog PDF123 explique comment l'API REST et MCP s'articulent.

Puis-je faire tourner PDF123 sur mon propre serveur ?

Oui. Le backend est le programme pdfx-server, qui s'exécute dans Docker. Pointez le SDK, la ligne de commande ou le serveur MCP vers lui avec PDFX_API_BASE : vos fichiers restent sur votre réseau. Voir Auto-hébergement pour l'installation et Entreprise pour les options de support.

FAQ

L'API PDF123 est-elle gratuite ?

Oui pour un usage anonyme. Les appels à l'API publique n'exigent ni compte ni clé. Les réponses hébergées incluent des en-têtes de limite de débit, ce qui permet à un client de ralentir avant de recevoir une réponse 429.

Ai-je besoin d'une clé d'API ?

Non pour l'API REST, le SDK et la ligne de commande avec le site public. Oui pour le point de terminaison MCP hébergé sur /mcp, qui répond 401 sans en-tête X-API-KEY. Vous pouvez créer une clé sur cette page après vous être connecté.

Quelle est la limite de taille des fichiers ?

Le site accepte des fichiers jusqu'à 500 Mo chacun. Le corps d'une requête directe à l'API peut atteindre 100 MiB, délimitation multipart comprise. Le SDK envoie automatiquement les entrées plus volumineuses par morceaux dès que le total dépasse 95 Mo.

Puis-je auto-héberger l'API ?

Oui. Lancez le serveur vous-même et définissez la base de l'API sur son adresse. Le SDK, la ligne de commande et le serveur MCP local acceptent tous une URL de base personnalisée.

Comment signaler une erreur ?

Copiez les champs code, reason et detail de la réponse d'erreur, ainsi que l'heure de la requête, et envoyez-les via la page de contact. N'envoyez pas le PDF lui-même, sauf si le support vous le demande.

Faut-il utiliser le SDK, la ligne de commande ou MCP ?

Utilisez le SDK dans du code TypeScript, la ligne de commande pour les scripts et les lots de fichiers locaux, et MCP quand un agent IA choisit l'outil. Les trois reposent sur le même catalogue et le même serveur : vous pouvez donc les combiner.