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.
| Interface | Idéale pour | Installation ou adresse | Guide |
|---|---|---|---|
| API REST | Tout langage, serveurs, scripts shell | https://pdf123.xyz/api/v1 | Référence de l'API |
| SDK TypeScript | Code Node, Bun et navigateur qui a besoin de types | npm install @pdf123/sdk | Guide du SDK |
| Ligne de commande | Terminaux, tâches CI, lots de fichiers locaux | npm install -g @pdf123/cli | Guide de la CLI |
| MCP | Agents IA comme Claude Code, Claude Desktop et Cursor | npx -y @pdf123/mcp ou https://pdf123.xyz/mcp | Guide 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.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfLa même fusion avec le SDK TypeScript :
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 :
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfComment 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…
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.pdfLe 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.
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.pdfComment 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 ?
| Limite | Valeur |
|---|---|
| Taille de fichier sur le site | 500 Mo par fichier |
| Corps d'une requête directe à l'API | 100 MiB, délimitation multipart comprise |
| Envoi par morceaux | Le 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 motif | Statut HTTP | Signification |
|---|---|---|
bad_request | 400 | Paramètres ou corps multipart invalides |
password_required | 400 | Le PDF est chiffré et aucun mot de passe n'a été envoyé |
invalid_pdf | 400 | Le fichier n'est pas un PDF ou est endommagé ; essayez Réparer un PDF |
page_out_of_range | 400 | Une page demandée n'existe pas |
not_found | 404 | Chemin d'opération inconnu |
rate_limited | 429 | Quota é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'outil | Point de terminaison de l'API | Commande CLI | Fonction |
|---|---|---|---|
| Fusionner | /general/merge-pdfs | pdfx merge | Réunir plusieurs PDF en un seul |
| Diviser | /general/split-pages | pdfx split | Découper un PDF en plusieurs fichiers |
| Compresser | /misc/compress-pdf | pdfx compress | Recompresser les flux du PDF pour réduire sa taille |
| Pivoter | /general/rotate-pdf | pdfx rotate | Changer l'orientation des pages |
| Protéger | /security/add-password | pdfx protect | Chiffrer un PDF avec un mot de passe |
| Déverrouiller | /security/remove-password | pdfx unlock | Retirer la protection par mot de passe |
| Filigrane | /security/add-watermark | pdfx watermark | Ajouter un filigrane de texte ou d'image |
| OCR | /misc/ocr-pdf | pdfx ocr | Lire un PDF numérisé et renvoyer du Markdown |
| PDF en Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Convertir un PDF en Markdown |
| PDF en Word | /convert/pdf/word | pdfx convert-to-word | Convertir un PDF en fichier Word modifiable |
| Infos du document | /security/get-info-on-pdf | pdfx get-info | Indiquer métadonnées, autorisations, polices et structure |
| Réparer | /misc/repair | pdfx repair | Reconstruire 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/mcppour 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.mdpour 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.jsonlddé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.