Ves al contingut principal
PPDF123

PDF123 per a desenvolupadors: API REST, SDK, línia d'ordres i MCP

La plataforma per a desenvolupadors de PDF123 ofereix les mateixes 97 eines PDF per quatre vies: una API REST descrita amb OpenAPI, un SDK de TypeScript, la línia d'ordres pdfx i servidors MCP per a agents d'IA. Les crides anònimes no requereixen compte ni clau d'API.

En aquesta pàgina

Com puc fer servir PDF123 des del codi?

Les quatre vies criden les mateixes operacions, de manera que unir fitxers dona el mateix resultat en totes. Tria segons on s'executa el teu codi.

ViaIdeal per aInstal·lació o adreçaGuia
API RESTQualsevol llenguatge, servidors, scripts de l'intèrpret d'ordreshttps://pdf123.xyz/api/v1Referència de l'API
SDK de TypeScriptCodi Node, Bun i de navegador que necessita tipusnpm install @pdf123/sdkGuia de l'SDK
Línia d'ordresTerminals, tasques de CI, lots de fitxers localsnpm install -g @pdf123/cliGuia de la CLI
MCPAgents d'IA com Claude Code, Claude Desktop i Cursornpx -y @pdf123/mcp o https://pdf123.xyz/mcpGuia de MCP

Fes servir l'API REST si el teu codi no és en TypeScript. Fes servir l'SDK si ho és, perquè les opcions de les eines estan tipades i es comproven abans de la pujada. Fes servir la línia d'ordres per a tasques puntuals i scripts. Fes servir MCP quan vulguis que un agent d'IA decideixi quina eina executar.

El catàleg té 97 eines. 58 tenen pàgina en aquest lloc web, com ara Uneix PDF, Parteix PDF i Comprimeix PDF. Les altres són operacions del backend sense pàgina web, i totes estan disponibles a l'SDK, a la línia d'ordres i a MCP.

Com executo la primera petició?

Uneix dos fitxers amb curl. La petició és un formulari multipart amb una part fileInput per fitxer.

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

La mateixa unió amb l'SDK de TypeScript:

SDK: unir dos 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 mateixa unió amb la línia d'ordres:

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

Com funciona l'autenticació?

Les crides anònimes a l'API pública no requereixen compte ni clau. Envia una clau d'API a la capçalera X-API-KEY quan vulguis identificar el teu tràfic o cridar el punt MCP allotjat, que sempre exigeix clau.

Inicia la sessió per crear una clau al quadre següent i guarda-la en un lloc segur.

S'està comprovant la sessió…

Crida l'API amb una claubash
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

L'SDK rep la clau com a apiKey. La línia d'ordres i el servidor MCP local la llegeixen de la variable d'entorn PDFX_API_KEY.

Nota

En un servidor autoallotjat, defineix la variable d'entorn SECURITY_CUSTOMGLOBALAPIKEY per establir una clau que el servidor accepti. Consulta Autoallotjament.

On és la referència de l'API?

L'API REST està documentada de dues maneres. Swagger UI permet provar cada punt final des del navegador. El document OpenAPI és la font llegible per màquina per als generadors de clients.

Cada operació és un POST sota l'URL base https://pdf123.xyz/api/v1, agrupada per categories. Per exemple, unir és /general/merge-pdfs i comprimir és /misc/compress-pdf.

Com encadeno diverses eines en una sola petició?

POST /api/v1/pipeline accepta les parts fileInput i un camp steps. Aquest camp és una matriu JSON d'objectes amb un op i params opcionals. Cada pas rep la sortida del pas anterior.

Unir i després comprimir, en una sola peticióbash
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

Com repeteixo una petició amb seguretat?

Envia una capçalera Idempotency-Key en qualsevol operació. Si es repeteix la mateixa petició en 24 hores, es retorna el primer resultat amb la capçalera Idempotency-Replayed: true en lloc d'executar-la de nou. Si fas servir la mateixa clau per a una altra petició, es rebutja. Els resultats de més de 32 MiB no es desen, de manera que repetir una petició així respon 409 i cal una clau nova.

Quins són els límits de mida i de freqüència?

LímitValor
Mida del fitxer al lloc web500 MB per fitxer
Cos d'una petició directa a l'API100 MiB, inclòs l'embolcall multipart
Pujada per fragmentsL'SDK passa automàticament a l'API de pujada per sobre de 95 MB en total

Les respostes porten les capçaleres X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset. Una resposta amb estat 429 hi afegeix Retry-After. Llegeix les capçaleres en lloc de suposar una quota fixa, perquè un servidor autoallotjat defineix els seus propis límits. L'entrada del blog sobre el límit de mida de la petició explica l'error que reps amb un cos massa gran.

Com és un error?

Els errors retornen application/problem+json amb els camps type, title, status, detail, code, reason i hint. Bifurca segons reason i recorre a code si cal. El text de detail està escrit per a persones i mai conté la sortida en brut de cap eina. Tots els codis són a Codis d'error.

Codi o motiuEstat HTTPSignificat
bad_request400Paràmetres o cos multipart no vàlids
password_required400El PDF està xifrat i no s'ha enviat cap contrasenya
invalid_pdf400El fitxer no és un PDF o està malmès; prova Repara PDF
page_out_of_range400Una pàgina sol·licitada no existeix
not_found404Ruta d'operació desconeguda
rate_limited429Quota esgotada; espera el temps de Retry-After

Quines eines puc cridar primer?

Aquestes dotze eines cobreixen la majoria de peticions. Fes servir la pàgina de l'eina per provar-la al navegador.

Pàgina de l'einaPunt final de l'APIOrdre de la CLIQuè fa
Uneix/general/merge-pdfspdfx mergeCombina diversos PDF en un
Parteix/general/split-pagespdfx splitDivideix un PDF en fitxers separats
Comprimeix/misc/compress-pdfpdfx compressTorna a comprimir els fluxos del PDF per reduir-ne la mida
Gira/general/rotate-pdfpdfx rotateCanvia l'orientació de les pàgines
Protegeix/security/add-passwordpdfx protectXifra un PDF amb una contrasenya
Desbloqueja/security/remove-passwordpdfx unlockTreu la protecció amb contrasenya
Marca d'aigua/security/add-watermarkpdfx watermarkAfegeix una marca d'aigua de text o d'imatge
OCR/misc/ocr-pdfpdfx ocrLlegeix un PDF escanejat i retorna Markdown
PDF a Markdown/convert/pdf/markdownpdfx pdf-to-markdownConverteix un PDF en Markdown
PDF a Word/convert/pdf/wordpdfx convert-to-wordConverteix un PDF en un fitxer Word editable
Informació del document/security/get-info-on-pdfpdfx get-infoInforma de les metadades, els permisos, les fonts i l'estructura
Repara/misc/repairpdfx repairReconstrueix l'estructura d'un PDF malmès

Els punts finals són relatius a https://pdf123.xyz/api/v1. Executa pdfx list o obre el document OpenAPI per veure les 97 eines.

Com faig servir PDF123 des d'un agent d'IA?

Un agent pot fer servir les eines de tres maneres:

  • Connectant un servidor MCP. La guia de MCP explica el servidor local @pdf123/mcp per als fitxers de la teva màquina i el punt allotjat a https://pdf123.xyz/mcp.
  • Carregant una skill d'agent. Les skills per a agents són fitxers SKILL.md per a Claude Code, Codex, Cursor i eines similars, una per al catàleg i una per a cada eina.
  • Llegint l'índex del lloc. /llms.txt llista les eines, l'API i el punt MCP en text pla, i /site.jsonld descriu el lloc com a dades estructurades.

L'entrada del blog «Built for AI Agents, Not Just Browsers» al blog de PDF123 explica com encaixen l'API REST i MCP.

Puc executar PDF123 al meu propi servidor?

Sí. El backend és el programa pdfx-server, que s'executa a Docker. Apunta-hi l'SDK, la línia d'ordres o el servidor MCP amb PDFX_API_BASE i els teus fitxers es queden a la teva xarxa. Consulta Autoallotjament per a la configuració i Empresa per a les opcions de suport.

FAQ

L'API de PDF123 és gratuïta?

Sí, per a l'ús anònim. Les crides a l'API pública no necessiten compte ni clau. Les respostes allotjades inclouen capçaleres de límit de freqüència, de manera que un client pot reduir el ritme abans de rebre una resposta 429.

Necessito una clau d'API?

No per a l'API REST, l'SDK i la línia d'ordres quan fas servir el lloc públic. Sí per al punt MCP allotjat a /mcp, que respon 401 sense la capçalera X-API-KEY. Pots crear una clau en aquesta pàgina un cop hagis iniciat la sessió.

Quin és el límit de mida dels fitxers?

El lloc web accepta fitxers de fins a 500 MB cadascun. El cos d'una petició directa a l'API pot arribar a 100 MiB, inclòs l'embolcall multipart. L'SDK puja automàticament per fragments les entrades més grans quan el total supera els 95 MB.

Puc autoallotjar l'API?

Sí. Executa tu mateix el servidor i defineix la base de l'API amb la seva adreça. L'SDK, la línia d'ordres i el servidor MCP local accepten un URL base personalitzat.

Com notifico un error?

Copia els camps code, reason i detail de la resposta d'error, més l'hora de la petició, i envia'ls per la pàgina de contacte. No enviïs el PDF mateix tret que el suport te'l demani.

He de fer servir l'SDK, la línia d'ordres o MCP?

Fes servir l'SDK dins de codi TypeScript, la línia d'ordres per a scripts i lots de fitxers locals, i MCP quan sigui un agent d'IA qui tria l'eina. Les tres vies fan servir el mateix catàleg i el mateix servidor, així que es poden combinar.