Nenda kwenye maudhui makuu
PPDF123

PDF123 kwa waendelezaji: REST API, SDK, mstari wa amri na MCP

Jukwaa la waendelezaji la PDF123 linatoa zana zile zile 97 za PDF kupitia njia nne: REST API iliyoelezwa kwa OpenAPI, TypeScript SDK, mstari wa amri wa pdfx na seva za MCP kwa mawakala wa AI. Maombi yasiyo na utambulisho hayahitaji akaunti wala ufunguo wa API.

Kwenye ukurasa huu

Nitumie PDF123 kutoka kwenye msimbo kwa njia ipi?

Njia zote nne zinaita operesheni zile zile, kwa hiyo kuunganisha faili kunatoa matokeo yaleyale kwa kila moja. Chagua kulingana na mahali msimbo wako unapoendeshwa.

NjiaInafaa kwaUsakinishaji au anwaniMwongozo
REST APILugha yoyote, seva, hati za shellhttps://pdf123.xyz/api/v1Marejeo ya API
TypeScript SDKMsimbo wa Node, Bun na kivinjari unaohitaji aina za datanpm install @pdf123/sdkMwongozo wa SDK
Mstari wa amriTerminali, kazi za CI, makundi ya faili za ndaninpm install -g @pdf123/cliMwongozo wa CLI
MCPMawakala wa AI kama Claude Code, Claude Desktop na Cursornpx -y @pdf123/mcp au https://pdf123.xyz/mcpMwongozo wa MCP

Tumia REST API ikiwa msimbo wako haujaandikwa kwa TypeScript. Tumia SDK ikiwa umeandikwa kwa TypeScript, kwa sababu chaguo za zana zina aina na hukaguliwa kabla ya kupakia. Tumia mstari wa amri kwa kazi za mara moja na hati za shell. Tumia MCP wakati wakala wa AI anapaswa kuamua zana ya kuendesha.

Katalogi ina zana 97. Zana 58 kati yake zina ukurasa kwenye tovuti hii, kama vile Unganisha PDF, Gawanya PDF na Bana PDF. Zilizobaki ni operesheni za backend zisizo na ukurasa wa wavuti, na zote zinapatikana kwenye SDK, mstari wa amri na MCP.

Ninawezaje kutuma ombi langu la kwanza?

Unganisha faili mbili kwa curl. Ombi ni fomu ya multipart yenye sehemu moja ya fileInput kwa kila faili.

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

Kuunganisha vilevile kwa TypeScript SDK:

SDK: unganisha PDF mbilits
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" });

Kuunganisha vilevile kwa mstari wa amri:

CLI: unganisha PDF mbilibash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

Uthibitishaji hufanyaje kazi?

Maombi yasiyo na utambulisho kwa API ya umma hayahitaji akaunti wala ufunguo. Tuma ufunguo wa API kwenye kichwa cha X-API-KEY unapotaka kutambulisha trafiki yako au kuita sehemu ya mwisho ya MCP iliyohifadhiwa kwenye seva zetu, ambayo daima inahitaji ufunguo.

Ingia ili kuunda ufunguo kwenye paneli iliyo hapa chini, kisha uuhifadhi mahali salama.

Inakagua kipindi chako…

Ita API kwa ufunguobash
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 inapokea ufunguo kama apiKey. Mstari wa amri na seva ya MCP ya ndani husoma ufunguo kutoka kwenye kigeu cha mazingira PDFX_API_KEY.

Kumbuka

Kwenye seva uliyojiendeshea mwenyewe, weka kigeu cha mazingira SECURITY_CUSTOMGLOBALAPIKEY ili kufafanua ufunguo mmoja ambao seva inaukubali. Tazama Self-host.

Marejeo ya API yako wapi?

REST API imeandikwa kwa namna mbili. Swagger UI inakuruhusu kujaribu kila sehemu ya mwisho kwenye kivinjari. Hati ya OpenAPI ni chanzo kinachosomeka na mashine kwa wazalishaji wa wateja.

Kila operesheni ni POST chini ya URL ya msingi https://pdf123.xyz/api/v1, iliyopangwa kwa kategoria. Kwa mfano, kuunganisha ni /general/merge-pdfs na kubana ni /misc/compress-pdf.

Ninawezaje kuunganisha zana kadhaa kwenye ombi moja?

POST /api/v1/pipeline inapokea sehemu za fileInput na sehemu ya steps. Sehemu ya steps ni safu ya JSON ya vitu vyenye op na params ya hiari. Kila hatua hupokea matokeo ya hatua iliyotangulia.

Unganisha, kisha bana, kwa ombi mojabash
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

Ninawezaje kurudia ombi kwa usalama?

Tuma kichwa cha Idempotency-Key kwenye operesheni yoyote. Ombi lilelile likirudiwa ndani ya saa 24, linarudisha matokeo ya kwanza pamoja na kichwa Idempotency-Replayed: true badala ya kuendeshwa tena. Kutumia ufunguo uleule kwa ombi tofauti kunakataliwa. Matokeo makubwa kuliko MiB 32 hayahifadhiwi, kwa hiyo kurudia ombi la aina hiyo kunajibiwa na 409 na kunahitaji ufunguo mpya.

Vikomo vya ukubwa na kiwango cha maombi ni vipi?

KikomoThamani
Ukubwa wa faili kwenye tovutiMB 500 kwa kila faili
Mwili wa ombi moja la moja kwa moja la APIMiB 100, pamoja na fremu za multipart
Upakiaji wa vipandeSDK inabadilisha kiotomatiki hadi API ya upakiaji jumla ikizidi MB 95

Majibu yanabeba vichwa X-RateLimit-Limit, X-RateLimit-Remaining na X-RateLimit-Reset. Jibu lenye hali 429 linaongeza Retry-After. Soma vichwa hivyo badala ya kudhani kiwango maalum, kwa sababu seva uliyojiendeshea mwenyewe huweka vikomo vyake. Chapisho la blogu kuhusu kikomo cha ukubwa wa ombi linaeleza hitilafu unayopata kwa mwili uliozidi ukubwa.

Hitilafu inaonekanaje?

Kushindwa kunarudisha application/problem+json yenye sehemu type, title, status, detail, code, reason na hint. Fanya uamuzi kwa reason na utumie code kama mbadala. Maandishi ya detail yameandikwa kwa ajili ya watu na hayana kamwe matokeo ghafi ya zana. Misimbo yote imeorodheshwa kwenye Misimbo ya hitilafu.

Msimbo au sababuHali ya HTTPMaana
bad_request400Vigezo au mwili wa multipart si sahihi
password_required400PDF imesimbwa na hakuna nenosiri lililotumwa
invalid_pdf400Faili si PDF au imeharibika; jaribu Rekebisha PDF
page_out_of_range400Ukurasa ulioombwa haupo
not_found404Njia ya operesheni haijulikani
rate_limited429Kiwango kimeisha; subiri Retry-After

Nianze kuita zana zipi?

Zana hizi kumi na mbili zinashughulikia maombi mengi. Tumia ukurasa wa zana kujaribu zana kwenye kivinjari.

Ukurasa wa zanaSehemu ya mwisho ya APIAmri ya CLIInafanya nini
Unganisha/general/merge-pdfspdfx mergeUnganisha PDF kadhaa kuwa moja
Gawanya/general/split-pagespdfx splitGawanya PDF kuwa faili tofauti
Bana/misc/compress-pdfpdfx compressBana tena mitiririko ya PDF ili kupunguza ukubwa
Zungusha/general/rotate-pdfpdfx rotateBadilisha mwelekeo wa kurasa
Weka nenosiri/security/add-passwordpdfx protectSimba PDF kwa nenosiri
Ondoa nenosiri/security/remove-passwordpdfx unlockOndoa ulinzi wa nenosiri
Weka alama ya maji/security/add-watermarkpdfx watermarkOngeza alama ya maji ya maandishi au picha
OCR/misc/ocr-pdfpdfx ocrSoma PDF iliyoskaniwa na urudishe Markdown
PDF kuwa Markdown/convert/pdf/markdownpdfx pdf-to-markdownGeuza PDF kuwa Markdown
PDF kuwa Word/convert/pdf/wordpdfx convert-to-wordGeuza PDF kuwa faili ya Word inayoharirika
Maelezo ya hati/security/get-info-on-pdfpdfx get-infoToa ripoti ya metadata, ruhusa, fonti na muundo
Rekebisha/misc/repairpdfx repairJenga upya muundo wa PDF iliyoharibika

Njia za sehemu za mwisho zinaanzia kwenye https://pdf123.xyz/api/v1. Endesha pdfx list au fungua hati ya OpenAPI ili kuona zana zote 97.

Ninatumiaje PDF123 kutoka kwa wakala wa AI?

Wakala anaweza kutumia zana kwa njia tatu:

  • Unganisha seva ya MCP. Mwongozo wa MCP unaeleza seva ya ndani @pdf123/mcp kwa faili zilizo kwenye kompyuta yako na sehemu ya mwisho iliyohifadhiwa kwenye https://pdf123.xyz/mcp.
  • Pakia skill ya wakala. Skill za mawakala ni faili za SKILL.md kwa Claude Code, Codex, Cursor na zana zinazofanana, moja kwa katalogi na moja kwa kila zana.
  • Soma faharasa ya tovuti. /llms.txt inaorodhesha zana, API na sehemu ya mwisho ya MCP kwa maandishi wazi, na /site.jsonld inaeleza tovuti kama data iliyopangwa.

Chapisho la blogu "Built for AI Agents, Not Just Browsers" kwenye blogu ya PDF123 linaeleza jinsi REST API na MCP zinavyokamilishana.

Je, naweza kuendesha PDF123 kwenye seva yangu mwenyewe?

Ndiyo. Backend ni programu ya pdfx-server, inayoendeshwa kwenye Docker. Elekeza SDK, mstari wa amri au seva ya MCP kwake kwa PDFX_API_BASE, na faili zako zitabaki kwenye mtandao wako. Tazama Self-host kwa maelekezo ya usanidi na Enterprise kwa chaguo za msaada.

Maswali yanayoulizwa mara kwa mara

Je, API ya PDF123 ni bure?

Ndiyo kwa matumizi bila utambulisho. Maombi kwa API ya umma hayahitaji akaunti wala ufunguo. Majibu kutoka kwenye seva yetu yanajumuisha vichwa vya kiwango cha maombi, kwa hiyo mteja anaweza kupunguza kasi kabla ya kupokea jibu la 429.

Je, ninahitaji ufunguo wa API?

Hapana kwa REST API, SDK na mstari wa amri unapotumia tovuti ya umma. Ndiyo kwa sehemu ya mwisho ya MCP iliyohifadhiwa kwenye seva zetu, /mcp, ambayo hujibu 401 bila kichwa cha X-API-KEY. Unaweza kuunda ufunguo kwenye ukurasa huu baada ya kuingia.

Kikomo cha ukubwa wa faili ni kipi?

Tovuti inakubali faili hadi MB 500 kila moja. Mwili wa ombi moja la moja kwa moja la API unaweza kufikia MiB 100 pamoja na fremu za multipart. SDK hupakia ingizo kubwa zaidi kwa vipande kiotomatiki jumla inapozidi MB 95.

Je, naweza kuendesha API kwenye seva yangu mwenyewe?

Ndiyo. Endesha seva mwenyewe na uweke msingi wa API uwe anwani yake. SDK, mstari wa amri na seva ya MCP ya ndani zote zinakubali URL ya msingi maalum.

Nitaripotije hitilafu?

Nakili sehemu za code, reason na detail kutoka kwenye jibu la tatizo, pamoja na wakati wa ombi, kisha utume kupitia ukurasa wa mawasiliano. Usitume PDF yenyewe isipokuwa msaada uiombe.

Nitumie SDK, mstari wa amri au MCP?

Tumia SDK ndani ya msimbo wa TypeScript, mstari wa amri kwa hati na makundi ya faili za ndani, na MCP wakala wa AI anapochagua zana. Zote tatu zinatumia katalogi ileile na seva ileile, kwa hiyo unaweza kuzichanganya.