Langkau ke kandungan utama
PPDF123

PDF123 untuk pembangun: REST API, SDK, baris perintah dan MCP

Platform pembangun PDF123 menyediakan 97 alat PDF yang sama melalui empat antara muka: REST API yang diperihalkan oleh OpenAPI, SDK TypeScript, baris perintah pdfx dan pelayan MCP untuk ejen AI. Panggilan tanpa nama tidak memerlukan akaun atau kunci API.

Dalam halaman ini

Bagaimana saya menggunakan PDF123 daripada kod?

Keempat-empat antara muka memanggil operasi yang sama, jadi gabungan fail memberikan hasil yang sama di setiap satu. Pilih mengikut tempat kod anda dijalankan.

Antara mukaPaling sesuai untukPemasangan atau alamatPanduan
REST APIMana-mana bahasa, pelayan, skrip shellhttps://pdf123.xyz/api/v1Rujukan API
SDK TypeScriptKod Node, Bun dan pelayar yang memerlukan jenisnpm install @pdf123/sdkPanduan SDK
Baris perintahTerminal, tugas CI, kelompok fail setempatnpm install -g @pdf123/cliPanduan CLI
MCPEjen AI seperti Claude Code, Claude Desktop dan Cursornpx -y @pdf123/mcp atau https://pdf123.xyz/mcpPanduan MCP

Gunakan REST API jika kod anda tidak ditulis dalam TypeScript. Gunakan SDK jika ya, kerana pilihan alat ditaip dan disemak sebelum dimuat naik. Gunakan baris perintah untuk tugas sekali jalan dan skrip shell. Gunakan MCP apabila ejen AI perlu memutuskan alat yang hendak dijalankan.

Katalog ini mempunyai 97 alat. 58 daripadanya mempunyai halaman di laman web ini, seperti Gabungkan PDF, Asingkan PDF dan Mampatkan PDF. Yang lain ialah operasi backend tanpa halaman web, dan semuanya tersedia dalam SDK, baris perintah dan MCP.

Bagaimana saya menjalankan permintaan pertama?

Gabungkan dua fail dengan curl. Permintaan itu ialah borang multipart dengan satu bahagian fileInput bagi setiap fail.

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

Penggabungan yang sama dengan SDK TypeScript:

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" });

Penggabungan yang sama dengan baris perintah:

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

Bagaimana pengesahan berfungsi?

Panggilan tanpa nama ke API awam tidak memerlukan akaun dan kunci. Hantar kunci API dalam pengepala X-API-KEY apabila anda mahu mengenal pasti trafik anda atau memanggil titik akhir MCP yang dihoskan, yang sentiasa memerlukan kunci.

Log masuk untuk mencipta kunci dalam panel di bawah, dan simpan di tempat yang selamat.

Menyemak sesi anda…

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

SDK menerima kunci itu sebagai apiKey. Baris perintah dan pelayan MCP setempat membacanya daripada pemboleh ubah persekitaran PDFX_API_KEY.

Nota

Pada pelayan yang dihoskan sendiri, tetapkan pemboleh ubah persekitaran SECURITY_CUSTOMGLOBALAPIKEY untuk menentukan satu kunci yang diterima oleh pelayan. Lihat Self-host.

Di mana rujukan API?

REST API didokumenkan dalam dua bentuk. Swagger UI membolehkan anda mencuba setiap titik akhir dalam pelayar. Dokumen OpenAPI ialah sumber yang boleh dibaca mesin untuk penjana klien.

Setiap operasi ialah POST di bawah URL asas https://pdf123.xyz/api/v1, dikumpulkan mengikut kategori. Sebagai contoh, gabung ialah /general/merge-pdfs dan mampat ialah /misc/compress-pdf.

Bagaimana saya merangkaikan beberapa alat dalam satu permintaan?

POST /api/v1/pipeline menerima bahagian fileInput dan medan steps. Medan steps ialah tatasusunan JSON berisi objek dengan op dan params pilihan. Setiap langkah menerima output langkah sebelumnya.

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

Bagaimana saya mencuba semula permintaan dengan selamat?

Hantar pengepala Idempotency-Key pada mana-mana operasi. Ulangan permintaan yang sama dalam tempoh 24 jam memulangkan hasil pertama dengan pengepala Idempotency-Replayed: true dan bukannya menjalankan semula operasi. Menggunakan kunci yang sama untuk permintaan lain akan ditolak. Hasil yang lebih besar daripada 32 MiB tidak disimpan, jadi ulangan permintaan sedemikian dijawab dengan 409 dan memerlukan kunci baharu.

Apakah had saiz dan had kadar?

HadNilai
Saiz fail di laman web500 MB bagi setiap fail
Satu badan permintaan API langsung100 MiB, termasuk bingkai multipart
Muat naik berketulSDK beralih secara automatik kepada API muat naik apabila jumlah melebihi 95 MB

Respons membawa pengepala X-RateLimit-Limit, X-RateLimit-Remaining dan X-RateLimit-Reset. Respons berstatus 429 menambah Retry-After. Baca pengepala itu dan jangan andaikan kuota tetap, kerana pelayan yang dihoskan sendiri menetapkan had sendiri. Catatan blog tentang had saiz permintaan menerangkan ralat yang anda terima untuk badan yang terlalu besar.

Bagaimana rupa ralat?

Kegagalan memulangkan application/problem+json dengan medan type, title, status, detail, code, reason dan hint. Bercabanglah mengikut reason dan gunakan code sebagai pilihan sandaran. Teks detail ditulis untuk manusia dan tidak pernah mengandungi output mentah alat. Semua kod disenaraikan di Kod ralat.

Kod atau sebabStatus HTTPMaksud
bad_request400Parameter atau badan multipart tidak sah
password_required400PDF disulitkan dan tiada kata laluan dihantar
invalid_pdf400Fail bukan PDF atau rosak; cuba Baiki PDF
page_out_of_range400Halaman yang diminta tidak wujud
not_found404Laluan operasi tidak dikenali
rate_limited429Kuota habis; tunggu Retry-After

Alat manakah yang boleh saya panggil dahulu?

Dua belas alat ini meliputi kebanyakan permintaan. Gunakan halaman alat untuk mencuba sesuatu alat dalam pelayar.

Halaman alatTitik akhir APIPerintah CLIFungsi
Gabungkan/general/merge-pdfspdfx mergeMenggabungkan beberapa PDF menjadi satu
Asingkan/general/split-pagespdfx splitMembahagikan PDF kepada fail berasingan
Mampatkan/misc/compress-pdfpdfx compressMemampat semula strim PDF untuk mengurangkan saiz
Putar/general/rotate-pdfpdfx rotateMenukar orientasi halaman
Lindungi/security/add-passwordpdfx protectMenyulitkan PDF dengan kata laluan
Buka kunci/security/remove-passwordpdfx unlockMembuang perlindungan kata laluan
Tanda air/security/add-watermarkpdfx watermarkMenambah tanda air teks atau imej
OCR/misc/ocr-pdfpdfx ocrMembaca PDF imbasan dan memulangkan Markdown
PDF ke Markdown/convert/pdf/markdownpdfx pdf-to-markdownMenukar PDF kepada Markdown
PDF ke Word/convert/pdf/wordpdfx convert-to-wordMenukar PDF kepada fail Word yang boleh disunting
Maklumat dokumen/security/get-info-on-pdfpdfx get-infoMelaporkan metadata, kebenaran, fon dan struktur
Baiki/misc/repairpdfx repairMembina semula struktur PDF yang rosak

Titik akhir adalah relatif kepada https://pdf123.xyz/api/v1. Jalankan pdfx list atau buka dokumen OpenAPI untuk melihat kesemua 97 alat.

Bagaimana saya menggunakan PDF123 daripada ejen AI?

Ejen boleh menggunakan alat ini dalam tiga cara:

  • Sambungkan pelayan MCP. Panduan MCP merangkumi pelayan setempat @pdf123/mcp untuk fail pada mesin anda dan titik akhir yang dihoskan di https://pdf123.xyz/mcp.
  • Muatkan skill ejen. Skill ejen ialah fail SKILL.md untuk Claude Code, Codex, Cursor dan alat serupa, satu untuk katalog dan satu bagi setiap alat.
  • Baca indeks laman. /llms.txt menyenaraikan alat, API dan titik akhir MCP dalam teks biasa, dan /site.jsonld memerihalkan laman sebagai data berstruktur.

Catatan blog "Built for AI Agents, Not Just Browsers" di blog PDF123 menerangkan bagaimana REST API dan MCP saling melengkapi.

Bolehkah saya menjalankan PDF123 pada pelayan sendiri?

Ya. Backend ialah program pdfx-server, yang berjalan dalam Docker. Halakan SDK, baris perintah atau pelayan MCP kepadanya dengan PDFX_API_BASE, dan fail anda kekal dalam rangkaian anda. Lihat Self-host untuk persediaan dan Enterprise untuk pilihan sokongan.

FAQ

Adakah API PDF123 percuma?

Ya untuk penggunaan tanpa nama. Panggilan ke API awam tidak memerlukan akaun atau kunci. Respons yang dihoskan menyertakan pengepala had kadar, supaya klien boleh memperlahankan permintaan sebelum menerima respons 429.

Adakah saya memerlukan kunci API?

Tidak untuk REST API, SDK dan baris perintah apabila anda menggunakan laman awam. Ya untuk titik akhir MCP yang dihoskan di /mcp, yang menjawab 401 tanpa pengepala X-API-KEY. Anda boleh mencipta kunci pada halaman ini selepas log masuk.

Apakah had saiz fail?

Laman web menerima fail sehingga 500 MB setiap satu. Satu badan permintaan API langsung boleh mencecah 100 MiB termasuk bingkai multipart. SDK memuat naik input yang lebih besar secara berketul dan automatik apabila jumlahnya melebihi 95 MB.

Bolehkah saya menghoskan API sendiri?

Ya. Jalankan pelayan itu sendiri dan tetapkan asas API kepada alamatnya. SDK, baris perintah dan pelayan MCP setempat semuanya menerima URL asas tersuai.

Bagaimana saya melaporkan ralat?

Salin medan code, reason dan detail daripada respons masalah, serta masa permintaan, dan hantarkannya melalui halaman hubungan. Jangan hantar PDF itu sendiri melainkan pihak sokongan memintanya.

Patutkah saya menggunakan SDK, baris perintah atau MCP?

Gunakan SDK dalam kod TypeScript, baris perintah untuk skrip dan kelompok fail setempat, dan MCP apabila ejen AI memilih alat. Ketiga-tiganya menggunakan katalog dan pelayan yang sama, jadi anda boleh menggabungkannya.