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änssnitt | Passar bäst för | Installation eller adress | Guide |
|---|---|---|---|
| REST API | Alla språk, servrar, shellskript | https://pdf123.xyz/api/v1 | API-referens |
| TypeScript-SDK | Node-, Bun- och webbläsarkod som behöver typer | npm install @pdf123/sdk | SDK-guide |
| Kommandorad | Terminaler, CI-jobb, omgångar med lokala filer | npm install -g @pdf123/cli | CLI-guide |
| MCP | AI-agenter som Claude Code, Claude Desktop och Cursor | npx -y @pdf123/mcp eller https://pdf123.xyz/mcp | MCP-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.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfSamma sammanslagning med TypeScript-SDK:n:
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:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfHur 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…
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.pdfSDK: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.
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.pdfHur 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äns | Värde |
|---|---|
| Filstorlek på webbplatsen | 500 MB per fil |
| En direkt API-begäran | 100 MiB, inklusive multipart-ramverket |
| Uppladdning i delar | SDK: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 orsak | HTTP-status | Betydelse |
|---|---|---|
bad_request | 400 | Ogiltiga parametrar eller ogiltig multipart-kropp |
password_required | 400 | PDF:en är krypterad och inget lösenord skickades |
invalid_pdf | 400 | Filen är ingen PDF eller är skadad; prova Reparera PDF |
page_out_of_range | 400 | En begärd sida finns inte |
not_found | 404 | Okänd operationssökväg |
rate_limited | 429 | Kvoten ä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.
| Verktygssida | API-slutpunkt | CLI-kommando | Vad det gör |
|---|---|---|---|
| Slå ihop | /general/merge-pdfs | pdfx merge | Kombinerar flera PDF:er till en |
| Dela | /general/split-pages | pdfx split | Delar en PDF i separata filer |
| Komprimera | /misc/compress-pdf | pdfx compress | Komprimerar om PDF-strömmar för att minska storleken |
| Rotera | /general/rotate-pdf | pdfx rotate | Ändrar sidornas orientering |
| Lägg till lösenord | /security/add-password | pdfx protect | Krypterar en PDF med ett lösenord |
| Ta bort lösenord | /security/remove-password | pdfx unlock | Tar bort lösenordsskyddet |
| Vattenmärke | /security/add-watermark | pdfx watermark | Lägger till ett text- eller bildvattenmärke |
| OCR | /misc/ocr-pdf | pdfx ocr | Läser en skannad PDF och returnerar Markdown |
| PDF till Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Konverterar en PDF till Markdown |
| PDF till Word | /convert/pdf/word | pdfx convert-to-word | Konverterar en PDF till en redigerbar Word-fil |
| Dokumentinfo | /security/get-info-on-pdf | pdfx get-info | Rapporterar metadata, behörigheter, typsnitt och struktur |
| Reparera | /misc/repair | pdfx repair | Bygger 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/mcpfö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.jsonldbeskriver 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.