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.
| Antarmuka | Cocok untuk | Instalasi atau alamat | Panduan |
|---|---|---|---|
| REST API | Bahasa apa pun, server, skrip shell | https://pdf123.xyz/api/v1 | Referensi API |
| SDK TypeScript | Kode Node, Bun, dan browser yang membutuhkan tipe | npm install @pdf123/sdk | Panduan SDK |
| Baris perintah | Terminal, tugas CI, kumpulan file lokal | npm install -g @pdf123/cli | Panduan CLI |
| MCP | Agen AI seperti Claude Code, Claude Desktop, dan Cursor | npx -y @pdf123/mcp atau https://pdf123.xyz/mcp | Panduan 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.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfPenggabungan yang sama dengan SDK TypeScript:
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:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfBagaimana 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…
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 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.
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.pdfBagaimana 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?
| Batas | Nilai |
|---|---|
| Ukuran file di situs web | 500 MB per file |
| Satu isi permintaan API langsung | 100 MiB, termasuk framing multipart |
| Unggahan bertahap | SDK 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 reason | Status HTTP | Arti |
|---|---|---|
bad_request | 400 | Parameter atau isi multipart tidak valid |
password_required | 400 | PDF terenkripsi dan tidak ada kata sandi yang dikirim |
invalid_pdf | 400 | File bukan PDF atau rusak; coba Perbaiki PDF |
page_out_of_range | 400 | Halaman yang diminta tidak ada |
not_found | 404 | Jalur operasi tidak dikenal |
rate_limited | 429 | Kuota 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 alat | Endpoint API | Perintah CLI | Fungsinya |
|---|---|---|---|
| Gabungkan | /general/merge-pdfs | pdfx merge | Menggabungkan beberapa PDF menjadi satu |
| Pisahkan | /general/split-pages | pdfx split | Membagi PDF menjadi file terpisah |
| Kompres | /misc/compress-pdf | pdfx compress | Mengompres ulang aliran data PDF agar ukurannya lebih kecil |
| Putar | /general/rotate-pdf | pdfx rotate | Mengubah orientasi halaman |
| Lindungi | /security/add-password | pdfx protect | Mengenkripsi PDF dengan kata sandi |
| Buka kunci | /security/remove-password | pdfx unlock | Menghapus perlindungan kata sandi |
| Tanda air | /security/add-watermark | pdfx watermark | Menambahkan tanda air teks atau gambar |
| OCR | /misc/ocr-pdf | pdfx ocr | Membaca PDF hasil pindai dan mengembalikan Markdown |
| PDF ke Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Mengubah PDF menjadi Markdown |
| PDF ke Word | /convert/pdf/word | pdfx convert-to-word | Mengubah PDF menjadi file Word yang bisa disunting |
| Informasi dokumen | /security/get-info-on-pdf | pdfx get-info | Melaporkan metadata, izin, font, dan struktur |
| Perbaiki | /misc/repair | pdfx repair | Membangun 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/mcpuntuk file di komputer Anda dan endpoint yang di-host dihttps://pdf123.xyz/mcp. - Muat skill agen. Skill agen adalah file
SKILL.mduntuk 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.jsonldmenjelaskan 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.