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 muka | Paling sesuai untuk | Pemasangan atau alamat | Panduan |
|---|---|---|---|
| REST API | Mana-mana bahasa, pelayan, skrip shell | https://pdf123.xyz/api/v1 | Rujukan API |
| SDK TypeScript | Kod Node, Bun dan pelayar yang memerlukan jenis | npm install @pdf123/sdk | Panduan SDK |
| Baris perintah | Terminal, tugas CI, kelompok fail setempat | npm install -g @pdf123/cli | Panduan CLI |
| MCP | Ejen AI seperti Claude Code, Claude Desktop dan Cursor | npx -y @pdf123/mcp atau https://pdf123.xyz/mcp | Panduan 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.
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 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…
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 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.
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 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?
| Had | Nilai |
|---|---|
| Saiz fail di laman web | 500 MB bagi setiap fail |
| Satu badan permintaan API langsung | 100 MiB, termasuk bingkai multipart |
| Muat naik berketul | SDK 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 sebab | Status HTTP | Maksud |
|---|---|---|
bad_request | 400 | Parameter atau badan multipart tidak sah |
password_required | 400 | PDF disulitkan dan tiada kata laluan dihantar |
invalid_pdf | 400 | Fail bukan PDF atau rosak; cuba Baiki PDF |
page_out_of_range | 400 | Halaman yang diminta tidak wujud |
not_found | 404 | Laluan operasi tidak dikenali |
rate_limited | 429 | Kuota 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 alat | Titik akhir API | Perintah CLI | Fungsi |
|---|---|---|---|
| Gabungkan | /general/merge-pdfs | pdfx merge | Menggabungkan beberapa PDF menjadi satu |
| Asingkan | /general/split-pages | pdfx split | Membahagikan PDF kepada fail berasingan |
| Mampatkan | /misc/compress-pdf | pdfx compress | Memampat semula strim PDF untuk mengurangkan saiz |
| Putar | /general/rotate-pdf | pdfx rotate | Menukar orientasi halaman |
| Lindungi | /security/add-password | pdfx protect | Menyulitkan PDF dengan kata laluan |
| Buka kunci | /security/remove-password | pdfx unlock | Membuang perlindungan kata laluan |
| Tanda air | /security/add-watermark | pdfx watermark | Menambah tanda air teks atau imej |
| OCR | /misc/ocr-pdf | pdfx ocr | Membaca PDF imbasan dan memulangkan Markdown |
| PDF ke Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Menukar PDF kepada Markdown |
| PDF ke Word | /convert/pdf/word | pdfx convert-to-word | Menukar PDF kepada fail Word yang boleh disunting |
| Maklumat dokumen | /security/get-info-on-pdf | pdfx get-info | Melaporkan metadata, kebenaran, fon dan struktur |
| Baiki | /misc/repair | pdfx repair | Membina 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/mcpuntuk fail pada mesin anda dan titik akhir yang dihoskan dihttps://pdf123.xyz/mcp. - Muatkan skill ejen. Skill ejen ialah fail
SKILL.mduntuk 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.jsonldmemerihalkan 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.