Naar de hoofdinhoud
PPDF123

PDF123 voor ontwikkelaars: REST API, SDK, opdrachtregel en MCP

Het ontwikkelaarsplatform van PDF123 biedt dezelfde 97 PDF-tools via vier interfaces: een REST API die met OpenAPI is beschreven, een TypeScript-SDK, de pdfx-opdrachtregel en MCP-servers voor AI-agents. Anonieme aanroepen vereisen geen account of API-sleutel.

Op deze pagina

Hoe gebruik ik PDF123 vanuit code?

Alle vier de interfaces roepen dezelfde bewerkingen aan, dus een samenvoeging geeft overal hetzelfde resultaat. Kies op basis van de plek waar je code draait.

InterfaceHet meest geschikt voorInstallatie of adresHandleiding
REST APIElke taal, servers, shellscriptshttps://pdf123.xyz/api/v1API-referentie
TypeScript-SDKNode-, Bun- en browsercode die typen nodig heeftnpm install @pdf123/sdkSDK-handleiding
OpdrachtregelTerminals, CI-taken, reeksen lokale bestandennpm install -g @pdf123/cliCLI-handleiding
MCPAI-agents zoals Claude Code, Claude Desktop en Cursornpx -y @pdf123/mcp of https://pdf123.xyz/mcpMCP-handleiding

Gebruik de REST API als je code niet in TypeScript is geschreven. Gebruik de SDK als dat wel zo is, want de opties van een tool zijn getypeerd en worden gecontroleerd vóór het uploaden. Gebruik de opdrachtregel voor eenmalige taken en shellscripts. Gebruik MCP als een AI-agent zelf moet bepalen welke tool wordt uitgevoerd.

De catalogus telt 97 tools. Voor 58 daarvan is er een pagina op deze website, zoals PDF samenvoegen, PDF splitsen en PDF comprimeren. De overige zijn backendbewerkingen zonder webpagina, en alle zijn beschikbaar in de SDK, de opdrachtregel en MCP.

Hoe voer ik mijn eerste verzoek uit?

Voeg twee bestanden samen met curl. Het verzoek is een multipart-formulier met per bestand één fileInput-onderdeel.

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

Dezelfde samenvoeging met de TypeScript-SDK:

SDK: merge two PDFsts
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" });

Dezelfde samenvoeging met de opdrachtregel:

CLI: merge two PDFsbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

Hoe werkt authenticatie?

Anonieme aanroepen van de openbare API hebben geen account en geen sleutel nodig. Stuur een API-sleutel mee in de header X-API-KEY als je je verkeer wilt identificeren of het gehoste MCP-eindpunt aanroept, dat altijd een sleutel vereist.

Log in om in het onderstaande paneel een sleutel aan te maken, en bewaar die op een veilige plek.

Je sessie wordt gecontroleerd…

Call the API with a keybash
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

De SDK neemt de sleutel over als apiKey. De opdrachtregel en de lokale MCP-server lezen hem uit de omgevingsvariabele PDFX_API_KEY.

Opmerking

Stel op een zelfgehoste server de omgevingsvariabele SECURITY_CUSTOMGLOBALAPIKEY in om één sleutel vast te leggen die de server accepteert. Zie Self-host.

Waar vind ik de API-referentie?

De REST API is op twee manieren gedocumenteerd. In Swagger UI probeer je elk eindpunt in de browser uit. Het OpenAPI-document is de machineleesbare bron voor clientgeneratoren.

Elke bewerking is een POST onder de basis-URL https://pdf123.xyz/api/v1, gegroepeerd per categorie. Samenvoegen is bijvoorbeeld /general/merge-pdfs en comprimeren is /misc/compress-pdf.

Hoe koppel ik meerdere tools in één verzoek?

POST /api/v1/pipeline neemt de fileInput-onderdelen en een veld steps. Het veld steps is een JSON-array van objecten met een op en optionele params. Elke stap krijgt de uitvoer van de vorige stap als invoer.

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

Hoe probeer ik een verzoek veilig opnieuw?

Stuur bij elke bewerking een header Idempotency-Key mee. Een herhaling van hetzelfde verzoek binnen 24 uur geeft het eerste resultaat terug met de header Idempotency-Replayed: true, in plaats van de bewerking opnieuw uit te voeren. Dezelfde sleutel gebruiken voor een ander verzoek wordt geweigerd. Resultaten groter dan 32 MiB worden niet opgeslagen, dus een herhaling van zo'n verzoek geeft 409 als antwoord en vereist een nieuwe sleutel.

Wat zijn de limieten voor grootte en aantal verzoeken?

LimietWaarde
Bestandsgrootte op de website500 MB per bestand
Eén directe API-aanvraag (body)100 MiB, inclusief multipart-opmaak
Uploaden in delenDe SDK schakelt automatisch over op de upload-API boven 95 MB in totaal

Antwoorden bevatten de headers X-RateLimit-Limit, X-RateLimit-Remaining en X-RateLimit-Reset. Bij status 429 komt daar Retry-After bij. Lees de headers in plaats van een vast quotum aan te nemen, want een zelfgehoste server bepaalt zijn eigen limieten. De blogpost over de limiet voor de aanvraaggrootte legt de fout uit die je krijgt bij een te grote body.

Hoe ziet een foutmelding eruit?

Fouten komen terug als application/problem+json met de velden type, title, status, detail, code, reason en hint. Vertak op reason en val terug op code. De tekst in detail is voor mensen geschreven en bevat nooit ruwe uitvoer van een tool. Alle codes staan op Foutcodes.

Code of redenHTTP-statusBetekenis
bad_request400Ongeldige parameters of ongeldige multipart-body
password_required400De PDF is versleuteld en er is geen wachtwoord meegestuurd
invalid_pdf400Het bestand is geen PDF of is beschadigd; probeer PDF repareren
page_out_of_range400Een opgevraagde pagina bestaat niet
not_found404Onbekend bewerkingspad
rate_limited429Quotum op; wacht op Retry-After

Welke tools kan ik als eerste aanroepen?

Deze twaalf tools dekken de meeste verzoeken. Gebruik de toolpagina om een tool in de browser uit te proberen.

ToolpaginaAPI-eindpuntCLI-opdrachtWat het doet
Samenvoegen/general/merge-pdfspdfx mergeMeerdere PDF's combineren tot één
Splitsen/general/split-pagespdfx splitEen PDF opdelen in losse bestanden
Comprimeren/misc/compress-pdfpdfx compressPDF-streams opnieuw comprimeren om de grootte te verkleinen
Roteren/general/rotate-pdfpdfx rotateDe paginarichting wijzigen
Beveiligen/security/add-passwordpdfx protectEen PDF met een wachtwoord versleutelen
Ontgrendelen/security/remove-passwordpdfx unlockWachtwoordbeveiliging verwijderen
Watermerk/security/add-watermarkpdfx watermarkEen tekst- of afbeeldingswatermerk toevoegen
OCR/misc/ocr-pdfpdfx ocrEen gescande PDF lezen en Markdown teruggeven
PDF naar Markdown/convert/pdf/markdownpdfx pdf-to-markdownEen PDF omzetten naar Markdown
PDF naar Word/convert/pdf/wordpdfx convert-to-wordEen PDF omzetten naar een bewerkbaar Word-bestand
Documentinfo/security/get-info-on-pdfpdfx get-infoMetadata, rechten, lettertypen en structuur weergeven
Repareren/misc/repairpdfx repairDe structuur van een beschadigde PDF herstellen

Eindpunten zijn relatief ten opzichte van https://pdf123.xyz/api/v1. Voer pdfx list uit of open het OpenAPI-document om alle 97 tools te zien.

Hoe gebruik ik PDF123 vanuit een AI-agent?

Een agent kan de tools op drie manieren gebruiken:

  • Koppel een MCP-server. De MCP-handleiding behandelt de lokale server @pdf123/mcp voor bestanden op je eigen machine en het gehoste eindpunt op https://pdf123.xyz/mcp.
  • Laad een agent-skill. Agent-skills zijn SKILL.md-bestanden voor Claude Code, Codex, Cursor en vergelijkbare programma's, een voor de catalogus en een voor elke tool.
  • Lees de site-index. /llms.txt somt de tools, de API en het MCP-eindpunt op in platte tekst, en /site.jsonld beschrijft de site als gestructureerde data.

De blogpost "Built for AI Agents, Not Just Browsers" op de PDF123-blog legt uit hoe de REST API en MCP samenwerken.

Kan ik PDF123 op mijn eigen server draaien?

Ja. De backend is het programma pdfx-server, dat in Docker draait. Richt de SDK, de opdrachtregel of de MCP-server erop met PDFX_API_BASE, en je bestanden blijven binnen je eigen netwerk. Zie Self-host voor de installatie en Enterprise voor ondersteuningsopties.

FAQ

Is de PDF123-API gratis?

Ja, voor anoniem gebruik. Aanroepen van de openbare API vereisen geen account en geen sleutel. Antwoorden van de gehoste dienst bevatten headers over de aanvraaglimiet, zodat een client kan vertragen voordat er een 429-antwoord komt.

Heb ik een API-sleutel nodig?

Nee voor de REST API, de SDK en de opdrachtregel als je de openbare site gebruikt. Ja voor het gehoste MCP-eindpunt op /mcp, dat zonder header X-API-KEY met 401 antwoordt. Na het inloggen maak je op deze pagina een sleutel aan.

Wat is de limiet voor de bestandsgrootte?

De website accepteert bestanden tot 500 MB per stuk. De body van één directe API-aanvraag mag maximaal 100 MiB zijn, inclusief multipart-opmaak. De SDK uploadt grotere invoer automatisch in delen zodra het totaal boven 95 MB komt.

Kan ik de API zelf hosten?

Ja. Draai de server zelf en stel de API-basis in op het adres ervan. De SDK, de opdrachtregel en de lokale MCP-server accepteren allemaal een eigen basis-URL.

Hoe meld ik een fout?

Kopieer de velden code, reason en detail uit het probleemantwoord, plus het tijdstip van het verzoek, en stuur ze via de contactpagina. Stuur de PDF zelf niet mee, tenzij de support daar om vraagt.

Moet ik de SDK, de opdrachtregel of MCP gebruiken?

Gebruik de SDK binnen TypeScript-code, de opdrachtregel voor scripts en reeksen lokale bestanden, en MCP als een AI-agent de tool kiest. Alle drie gebruiken dezelfde catalogus en dezelfde server, dus je kunt ze combineren.