Till huvudinnehållet
PPDF123

PDF123 för utvecklare: REST API, SDK, kommandorad och MCP

PDF123:s utvecklarplattform ger tillgång till samma 97 PDF-verktyg genom fyra gränssnitt: ett REST API som beskrivs med OpenAPI, en TypeScript-SDK, kommandoraden pdfx och MCP-servrar för AI-agenter. Anonyma anrop kräver varken konto eller API-nyckel.

På den här sidan

Hur använder jag PDF123 från kod?

Alla fyra gränssnitten anropar samma operationer, så en sammanslagning ger samma resultat i vart och ett av dem. Välj utifrån var din kod körs.

GränssnittPassar bäst förInstallation eller adressGuide
REST APIAlla språk, servrar, shellskripthttps://pdf123.xyz/api/v1API-referens
TypeScript-SDKNode-, Bun- och webbläsarkod som behöver typernpm install @pdf123/sdkSDK-guide
KommandoradTerminaler, CI-jobb, omgångar med lokala filernpm install -g @pdf123/cliCLI-guide
MCPAI-agenter som Claude Code, Claude Desktop och Cursornpx -y @pdf123/mcp eller https://pdf123.xyz/mcpMCP-guide

Använd REST API:t om din kod inte är skriven i TypeScript. Använd SDK:n om den är det, eftersom verktygens alternativ är typade och kontrolleras före uppladdning. Använd kommandoraden för engångsjobb och shellskript. Använd MCP när en AI-agent ska avgöra vilket verktyg som körs.

Katalogen innehåller 97 verktyg. 58 av dem har en egen sida på webbplatsen, till exempel Slå ihop PDF, Dela PDF och Komprimera PDF. De övriga är backend-operationer utan webbsida, och alla finns i SDK:n, på kommandoraden och i MCP.

Hur kör jag min första begäran?

Slå ihop två filer med curl. Begäran är ett multipart-formulär med en fileInput-del per fil.

REST: slå ihop två PDF:erbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

Samma sammanslagning med TypeScript-SDK:n:

SDK: slå ihop två PDF:erts
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" });

Samma sammanslagning från kommandoraden:

CLI: slå ihop två PDF:erbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

Hur fungerar autentisering?

Anonyma anrop till det publika API:t kräver varken konto eller nyckel. Skicka en API-nyckel i rubriken X-API-KEY när du vill att din trafik ska kunna identifieras eller när du anropar den hostade MCP-slutpunkten, som alltid kräver en nyckel.

Logga in för att skapa en nyckel i panelen nedan och förvara den på ett säkert ställe.

Kontrollerar din session…

Anropa API:t med en nyckelbash
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

SDK:n tar emot nyckeln som apiKey. Kommandoraden och den lokala MCP-servern läser den från miljövariabeln PDFX_API_KEY.

Obs

På en egen server anger du miljövariabeln SECURITY_CUSTOMGLOBALAPIKEY för att bestämma en nyckel som servern godtar. Se Self-host.

Var finns API-referensen?

REST API:t dokumenteras i två former. I Swagger UI kan du prova varje slutpunkt i webbläsaren. OpenAPI-dokumentet är den maskinläsbara källan för klientgeneratorer.

Varje operation är ett POST under bas-URL:en https://pdf123.xyz/api/v1, grupperat efter kategori. Sammanslagning är till exempel /general/merge-pdfs och komprimering är /misc/compress-pdf.

Hur kedjar jag flera verktyg i en och samma begäran?

POST /api/v1/pipeline tar emot fileInput-delarna och ett steps-fält. Fältet steps är en JSON-array med objekt som har en op och valfria params. Varje steg får föregående stegs resultat.

Slå ihop och komprimera i en begäranbash
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

Hur gör jag om en begäran på ett säkert sätt?

Skicka rubriken Idempotency-Key med valfri operation. Om samma begäran upprepas inom 24 timmar returneras det första resultatet med rubriken Idempotency-Replayed: true i stället för att operationen körs igen. Om samma nyckel används för en annan begäran avvisas den. Resultat som är större än 32 MiB sparas inte, så en upprepning av en sådan begäran besvaras med 409 och kräver en ny nyckel.

Vilka gränser gäller för storlek och frekvens?

GränsVärde
Filstorlek på webbplatsen500 MB per fil
En direkt API-begäran100 MiB, inklusive multipart-ramverket
Uppladdning i delarSDK:n växlar automatiskt till uppladdnings-API:t när totalen överstiger 95 MB

Svaren innehåller rubrikerna X-RateLimit-Limit, X-RateLimit-Remaining och X-RateLimit-Reset. Ett svar med status 429 lägger till Retry-After. Läs rubrikerna i stället för att räkna med en fast kvot, eftersom en egen server sätter sina egna gränser. Blogginlägget om gränsen för begärans storlek förklarar felet du får för en för stor begärandekropp.

Hur ser ett fel ut?

Fel returneras som application/problem+json med fälten type, title, status, detail, code, reason och hint. Förgrena på reason och använd code som reserv. Texten i detail är skriven för människor och innehåller aldrig verktygets råa utdata. Alla koder finns listade under Felkoder.

Kod eller orsakHTTP-statusBetydelse
bad_request400Ogiltiga parametrar eller ogiltig multipart-kropp
password_required400PDF:en är krypterad och inget lösenord skickades
invalid_pdf400Filen är ingen PDF eller är skadad; prova Reparera PDF
page_out_of_range400En begärd sida finns inte
not_found404Okänd operationssökväg
rate_limited429Kvoten är slut; vänta på Retry-After

Vilka verktyg kan jag anropa först?

Dessa tolv verktyg täcker de flesta begäranden. Använd verktygets sida för att prova det i webbläsaren.

VerktygssidaAPI-slutpunktCLI-kommandoVad det gör
Slå ihop/general/merge-pdfspdfx mergeKombinerar flera PDF:er till en
Dela/general/split-pagespdfx splitDelar en PDF i separata filer
Komprimera/misc/compress-pdfpdfx compressKomprimerar om PDF-strömmar för att minska storleken
Rotera/general/rotate-pdfpdfx rotateÄndrar sidornas orientering
Lägg till lösenord/security/add-passwordpdfx protectKrypterar en PDF med ett lösenord
Ta bort lösenord/security/remove-passwordpdfx unlockTar bort lösenordsskyddet
Vattenmärke/security/add-watermarkpdfx watermarkLägger till ett text- eller bildvattenmärke
OCR/misc/ocr-pdfpdfx ocrLäser en skannad PDF och returnerar Markdown
PDF till Markdown/convert/pdf/markdownpdfx pdf-to-markdownKonverterar en PDF till Markdown
PDF till Word/convert/pdf/wordpdfx convert-to-wordKonverterar en PDF till en redigerbar Word-fil
Dokumentinfo/security/get-info-on-pdfpdfx get-infoRapporterar metadata, behörigheter, typsnitt och struktur
Reparera/misc/repairpdfx repairBygger upp strukturen i en skadad PDF på nytt

Slutpunkterna är relativa till https://pdf123.xyz/api/v1. Kör pdfx list eller öppna OpenAPI-dokumentet för att se alla 97 verktyg.

Hur använder jag PDF123 från en AI-agent?

En agent kan använda verktygen på tre sätt:

  • Anslut en MCP-server. MCP-guiden beskriver den lokala servern @pdf123/mcp för filer på din dator och den hostade slutpunkten på https://pdf123.xyz/mcp.
  • Läs in en agent-skill. Agent-skills är SKILL.md-filer för Claude Code, Codex, Cursor och liknande verktyg, en för katalogen och en för varje verktyg.
  • Läs webbplatsens index. /llms.txt listar verktygen, API:t och MCP-slutpunkten som ren text, och /site.jsonld beskriver webbplatsen som strukturerad data.

Blogginlägget "Byggd för AI-agenter, inte bara webbläsare" på PDF123-bloggen förklarar hur REST API:t och MCP hänger ihop.

Kan jag köra PDF123 på min egen server?

Ja. Backend är programmet pdfx-server, som körs i Docker. Peka SDK:n, kommandoraden eller MCP-servern mot den med PDFX_API_BASE, så stannar filerna i ditt eget nätverk. Se Self-host för installation och Enterprise för supportalternativ.

Vanliga frågor

Är PDF123:s API gratis?

Ja, för anonym användning. Anrop till det publika API:t kräver inget konto och ingen nyckel. Svar från den hostade tjänsten innehåller rubriker om begränsningar, så en klient kan sakta ner innan den får ett 429-svar.

Behöver jag en API-nyckel?

Nej för REST API:t, SDK:n och kommandoraden när du använder den publika webbplatsen. Ja för den hostade MCP-slutpunkten på /mcp, som svarar 401 utan rubriken X-API-KEY. Du kan skapa en nyckel på den här sidan efter inloggning.

Vilken är filstorleksgränsen?

Webbplatsen tar emot filer upp till 500 MB vardera. En enskild direkt API-begäran får vara upp till 100 MiB inklusive multipart-ramverket. SDK:n laddar upp större indata i delar automatiskt när totalen passerar 95 MB.

Kan jag köra API:t själv?

Ja. Kör servern själv och ange dess adress som API-bas. SDK:n, kommandoraden och den lokala MCP-servern godtar alla en egen bas-URL.

Hur rapporterar jag ett fel?

Kopiera fälten code, reason och detail från problemsvaret, tillsammans med tidpunkten för begäran, och skicka dem via kontaktsidan. Skicka inte själva PDF:en om inte supporten ber om den.

Ska jag använda SDK:n, kommandoraden eller MCP?

Använd SDK:n i TypeScript-kod, kommandoraden för skript och omgångar med lokala filer, och MCP när en AI-agent väljer verktyget. Alla tre använder samma katalog och samma server, så du kan kombinera dem.