Lewati ke konten utama
PPDF123

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

Platform pengembang PDF123 menyediakan 97 alat PDF yang sama lewat empat antarmuka: REST API yang dijelaskan dengan OpenAPI, SDK TypeScript, baris perintah pdfx, dan server MCP untuk agen AI. Panggilan anonim tidak memerlukan akun atau kunci API.

Di halaman ini

Bagaimana cara memakai PDF123 dari kode?

Keempat antarmuka memanggil operasi yang sama, jadi penggabungan memberi hasil yang sama di semuanya. Pilih sesuai tempat kode Anda berjalan.

AntarmukaCocok untukInstalasi atau alamatPanduan
REST APIBahasa apa pun, server, skrip shellhttps://pdf123.xyz/api/v1Referensi API
SDK TypeScriptKode Node, Bun, dan browser yang membutuhkan tipenpm install @pdf123/sdkPanduan SDK
Baris perintahTerminal, tugas CI, kumpulan file lokalnpm install -g @pdf123/cliPanduan CLI
MCPAgen AI seperti Claude Code, Claude Desktop, dan Cursornpx -y @pdf123/mcp atau https://pdf123.xyz/mcpPanduan MCP

Pakai REST API jika kode Anda tidak ditulis dalam TypeScript. Pakai SDK jika ya, karena opsi alat bertipe dan diperiksa sebelum diunggah. Pakai baris perintah untuk pekerjaan sekali jalan dan skrip shell. Pakai MCP jika agen AI yang memutuskan alat mana yang dijalankan.

Katalog berisi 97 alat. Sebanyak 58 di antaranya punya halaman di situs ini, misalnya Gabungkan PDF, Pisahkan PDF, dan Kompres PDF. Sisanya adalah operasi backend tanpa halaman web, dan semuanya tersedia di SDK, baris perintah, dan MCP.

Bagaimana cara menjalankan permintaan pertama?

Gabungkan dua file dengan curl. Permintaannya berupa formulir multipart dengan satu bagian fileInput untuk setiap file.

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 cara kerja autentikasi?

Panggilan anonim ke API publik tidak memerlukan akun maupun kunci. Kirim kunci API di header X-API-KEY jika Anda ingin mengenali lalu lintas Anda atau memanggil endpoint MCP yang di-host, yang selalu memerlukan kunci.

Masuk untuk membuat kunci di panel di bawah, lalu simpan di tempat yang aman.

Memeriksa 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 sebagai apiKey. Baris perintah dan server MCP lokal membacanya dari variabel lingkungan PDFX_API_KEY.

Catatan

Pada server self-host, setel variabel lingkungan SECURITY_CUSTOMGLOBALAPIKEY untuk menentukan satu kunci yang diterima server. Lihat Self-host.

Di mana referensi API?

REST API didokumentasikan dalam dua bentuk. Swagger UI memungkinkan Anda mencoba setiap endpoint di browser. Dokumen OpenAPI adalah sumber yang dapat dibaca mesin untuk generator klien.

Setiap operasi adalah POST di bawah URL dasar https://pdf123.xyz/api/v1, dikelompokkan menurut kategori. Misalnya, merge adalah /general/merge-pdfs dan compress adalah /misc/compress-pdf.

Bagaimana cara merangkai beberapa alat dalam satu permintaan?

POST /api/v1/pipeline menerima bagian fileInput dan satu kolom steps. Kolom steps adalah array JSON berisi objek dengan op dan params opsional. Setiap langkah menerima keluaran 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 cara mengulang permintaan dengan aman?

Kirim header Idempotency-Key pada operasi apa pun. Pengulangan permintaan yang sama dalam 24 jam mengembalikan hasil pertama dengan header Idempotency-Replayed: true, tanpa dijalankan lagi. Memakai kunci yang sama untuk permintaan yang berbeda akan ditolak. Hasil yang lebih besar dari 32 MiB tidak disimpan, sehingga pengulangan permintaan seperti itu dijawab dengan 409 dan memerlukan kunci baru.

Apa saja batas ukuran dan laju?

BatasNilai
Ukuran file di situs web500 MB per file
Satu isi permintaan API langsung100 MiB, termasuk framing multipart
Unggahan bertahapSDK beralih ke API unggah secara otomatis jika totalnya di atas 95 MB

Respons membawa header X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset. Respons berstatus 429 menambahkan Retry-After. Baca header tersebut dan jangan berasumsi kuotanya tetap, karena server self-host menetapkan batasnya sendiri. Artikel blog tentang batas ukuran permintaan menjelaskan galat yang muncul untuk isi permintaan yang terlalu besar.

Seperti apa tampilan galat?

Kegagalan mengembalikan application/problem+json dengan kolom type, title, status, detail, code, reason, dan hint. Percabangan logika berdasarkan reason, lalu gunakan code sebagai cadangan. Teks detail ditulis untuk manusia dan tidak pernah berisi keluaran mentah dari alat. Semua kode tercantum di Kode galat.

Kode atau reasonStatus HTTPArti
bad_request400Parameter atau isi multipart tidak valid
password_required400PDF terenkripsi dan tidak ada kata sandi yang dikirim
invalid_pdf400File bukan PDF atau rusak; coba Perbaiki PDF
page_out_of_range400Halaman yang diminta tidak ada
not_found404Jalur operasi tidak dikenal
rate_limited429Kuota habis; tunggu hingga Retry-After

Alat mana yang bisa saya panggil lebih dulu?

Kedua belas alat ini mencakup sebagian besar permintaan. Gunakan halaman alat untuk mencoba alat di browser.

Halaman alatEndpoint APIPerintah CLIFungsinya
Gabungkan/general/merge-pdfspdfx mergeMenggabungkan beberapa PDF menjadi satu
Pisahkan/general/split-pagespdfx splitMembagi PDF menjadi file terpisah
Kompres/misc/compress-pdfpdfx compressMengompres ulang aliran data PDF agar ukurannya lebih kecil
Putar/general/rotate-pdfpdfx rotateMengubah orientasi halaman
Lindungi/security/add-passwordpdfx protectMengenkripsi PDF dengan kata sandi
Buka kunci/security/remove-passwordpdfx unlockMenghapus perlindungan kata sandi
Tanda air/security/add-watermarkpdfx watermarkMenambahkan tanda air teks atau gambar
OCR/misc/ocr-pdfpdfx ocrMembaca PDF hasil pindai dan mengembalikan Markdown
PDF ke Markdown/convert/pdf/markdownpdfx pdf-to-markdownMengubah PDF menjadi Markdown
PDF ke Word/convert/pdf/wordpdfx convert-to-wordMengubah PDF menjadi file Word yang bisa disunting
Informasi dokumen/security/get-info-on-pdfpdfx get-infoMelaporkan metadata, izin, font, dan struktur
Perbaiki/misc/repairpdfx repairMembangun ulang struktur PDF yang rusak

Endpoint bersifat relatif terhadap https://pdf123.xyz/api/v1. Jalankan pdfx list atau buka dokumen OpenAPI untuk melihat semua 97 alat.

Bagaimana cara memakai PDF123 dari agen AI?

Agen dapat memakai alat dengan tiga cara:

  • Hubungkan server MCP. Panduan MCP membahas server lokal @pdf123/mcp untuk file di komputer Anda dan endpoint yang di-host di https://pdf123.xyz/mcp.
  • Muat skill agen. Skill agen adalah file SKILL.md untuk Claude Code, Codex, Cursor, dan alat serupa, satu untuk katalog dan satu untuk setiap alat.
  • Baca indeks situs. /llms.txt mencantumkan alat, API, dan endpoint MCP dalam teks biasa, dan /site.jsonld menjelaskan situs sebagai data terstruktur.

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

Bisakah saya menjalankan PDF123 di server sendiri?

Bisa. Backend-nya adalah program pdfx-server, yang berjalan di Docker. Arahkan SDK, baris perintah, atau server MCP ke sana dengan PDFX_API_BASE, dan file Anda tetap berada di jaringan Anda. Lihat Self-host untuk pengaturan dan Enterprise untuk opsi dukungan.

FAQ

Apakah API PDF123 gratis?

Ya untuk pemakaian anonim. Panggilan ke API publik tidak memerlukan akun atau kunci. Respons dari layanan yang di-host menyertakan header batas laju, sehingga klien bisa memperlambat diri sebelum menerima respons 429.

Apakah saya perlu kunci API?

Tidak untuk REST API, SDK, dan baris perintah jika Anda memakai situs publik. Ya untuk endpoint MCP yang di-host di /mcp, yang menjawab 401 tanpa header X-API-KEY. Anda bisa membuat kunci di halaman ini setelah masuk.

Berapa batas ukuran file?

Situs web menerima file hingga 500 MB per file. Satu isi permintaan API langsung boleh sampai 100 MiB, termasuk framing multipart. SDK mengunggah input yang lebih besar secara bertahap dan otomatis begitu totalnya melewati 95 MB.

Bisakah saya menjalankan API di server sendiri?

Bisa. Jalankan server sendiri dan setel basis API ke alamatnya. SDK, baris perintah, dan server MCP lokal semuanya menerima URL dasar kustom.

Bagaimana cara melaporkan galat?

Salin kolom code, reason, dan detail dari respons problem, beserta waktu permintaan, lalu kirim lewat halaman kontak. Jangan kirim PDF-nya kecuali tim dukungan memintanya.

Sebaiknya saya pakai SDK, baris perintah, atau MCP?

Pakai SDK di dalam kode TypeScript, baris perintah untuk skrip dan kumpulan file lokal, dan MCP jika agen AI yang memilih alat. Ketiganya memakai katalog dan server yang sama, sehingga bisa dikombinasikan.