Operasi yang sama, empat klien: browser, curl, MCP, pdfx
Merge PDF123 yang sama bisa dipanggil lewat empat klien: form browser, curl ke /api/v1/general/merge-pdfs, MCP di /mcp, dan pdfx lokal atau cloud terhadap base API.
Empat klien tampak seperti empat produk. Padahal semuanya berbagi satu katalog. Ambil Merge sebagai contoh konkret: gabungkan PDF menurut urutan unggahan tanpa meraster halaman menjadi gambar. Pola yang sama berlaku untuk setiap alat katalog lainnya (compress, OCR, convert, dan sisanya): satu id operasi, empat cara memanggilnya.
Browser
Buka /merge, tambahkan berkas sesuai urutan yang Anda inginkan, klik Process, lalu unduh. Tidak perlu akun untuk alat katalog. Blok "Call this from code" di halaman itu menyusun curl dari field yang sama dengan yang dikirim formulir, sehingga antarmuka dan kontrak HTTP tetap selaras.
Blok itu bukan teks pemasaran. Ia dihasilkan dari definisi alat yang sudah dipakai portal untuk formulirnya, dan itulah sebabnya penggantian nama parameter langsung muncul di kedua tempat sekaligus. Jika formulir menerima opsi sortType=byFileName, contoh curl-nya juga membawa field yang sama.
curl / REST
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
Panggilan katalog anonim tidak memerlukan key. Key dari Developers memberi otomasi identitas yang stabil (dan memberi server self-host sebuah gerbang). OpenAPI ada di /v1/openapi.json.
Untuk pekerjaan bertahap, POST /api/v1/pipeline menerima operasi berurutan di field steps (misalnya merge, lalu watermark, lalu compress). Kirim Idempotency-Key bila percobaan ulang tidak boleh menjalankan pekerjaan dua kali; pengulangan yang berhasil bisa kembali dengan Idempotency-Replayed. Kegagalan memakai application/problem+json dengan kode yang stabil seperti rate_limited dan bad_request (Galat API di Developers).
Respons hosted juga menyertakan X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset; HTTP 429 menyertakan Retry-After. Perlakukan header itu sebagai anggaran yang berlaku saat itu, bukan angka yang Anda hafal dari artikel blog (pembatasan laju untuk pemanggil anonim).
MCP
Agen yang memahami Model Context Protocol tersambung ke /mcp, menemukan merge sebagai sebuah alat, lalu memanggilnya dengan aturan API key yang sama seperti REST. Dokumentasi: MCP untuk pengembang.
MCP bukan katalog kedua. Ia adalah protokol penemuan dan pemanggilan di atas operasi yang sama dengan yang dicantumkan OpenAPI. Jika sebuah operasi tidak muncul di MCP, itu bug di sisi server, bukan peta jalan produk yang terpisah. Pasangkan MCP dengan /llms.txt bila Anda menginginkan indeks prosa dari alat-alatnya sebelum klien tersambung.
CLI pdfx
pdf-core lokal:
pdfx merge a.pdf b.pdf -o merged.pdf
Atau server yang sama dengan yang dipakai portal:
pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf
Mode lokal tidak pernah mengunggah apa pun; mode cloud menyentuh base URL Anda dengan bentuk multipart yang sama seperti curl. Skill untuk agen coding di dist/skills/pdf-toolbox/SKILL.md mendokumentasikan bentuk merge dan pipeline yang sama agar agen tidak menciptakan OpenAPI kedua.
OCR lewat salah satu klien ini tetap mengembalikan Markdown dari /api/v1/misc/ocr-pdf, bukan lapisan teks tersembunyi. Fakta itu adalah bagian dari kontrak bersama: mengubah tipe kembalian di satu klien tanpa yang lain akan mematahkan janji "operasi yang sama". Compress tetap di /api/v1/misc/compress-pdf untuk rekompresi stream; itu operasi yang berbeda dari merge, tetapi dapat dijangkau dengan empat cara yang sama.
Mengapa kesamaan itu penting
Jika merge di browser dan merge lewat API pernah menyimpang, otomasi akan diam-diam rusak sementara halaman demo tetap terlihat baik. Satu operasi dengan empat cara memanggil, itulah intinya. Portal adalah klien untuk kenyamanan, bukan implementasi kedua dari merge, compress, atau OCR.
Itulah pula alasan tidak ada fork desktop: pohon antarmuka kelima akan menciptakan kembali masalah penyimpangan itu dengan nama biner yang berbeda. Kerangka yang lebih luas: Dibangun untuk agen AI, bukan hanya browser. Untuk keputusan soal desktop, lihat Mengapa kami melewati aplikasi desktop. Untuk menegakkan API di jaringan Anda, lihat Self-host.