Operasi Sama, Empat Klien: Pelayar, curl, MCP, pdfx

Empat klien kelihatan seperti empat produk. Mereka sebenarnya berkongsi satu katalog. Ambil Gabungkan PDF sebagai tugasan konkrit: gabungkan PDF dalam susunan muat naik tanpa meraster halaman menjadi imej. Corak yang sama terpakai untuk setiap alat katalog yang lain (compress, OCR, convert, dan selebihnya): satu ID operasi, empat cara memanggilnya.

Pelayar

Buka /merge, tambah fail dalam susunan yang anda mahukan, klik Process, muat turun. Tiada akaun diperlukan untuk alat katalog. Blok “Call this from code” pada halaman itu membina curl daripada medan yang sama yang dihantar oleh borang, supaya antara muka dan kontrak HTTP kekal sejajar.

Blok itu bukan bahan pemasaran. Ia dijana daripada takrifan alat yang sudah digunakan oleh portal untuk borang, dan itulah sebabnya penamaan semula parameter muncul di kedua-dua tempat serentak. Jika borang menerima pilihan sortType=byFileName, contoh curl itu juga boleh membawa medan 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 tanpa nama tidak memerlukan kunci. Kunci daripada Pembangun memberikan automasi identiti yang stabil (dan pelayan self-host satu kawalan akses). OpenAPI berada di /v1/openapi.json.

Untuk tugasan berbilang langkah, POST /api/v1/pipeline menerima operasi tersusun dalam medan steps (contohnya merge, kemudian watermark, kemudian compress). Hantar Idempotency-Key apabila cubaan semula tidak boleh menjalankan kerja itu dua kali; pemutaran semula yang berjaya boleh dipulangkan dengan Idempotency-Replayed. Kegagalan menggunakan application/problem+json dengan kod yang stabil seperti rate_limited dan bad_request (Ralat API).

Respons yang dihoskan juga menyatakan X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset; HTTP 429 menyertakan Retry-After. Anggap pengepala itu sebagai bajet semasa, bukan nombor yang dihafal daripada catatan blog (had kadar tanpa nama).

MCP

Ejen yang menggunakan Model Context Protocol menyambung ke /mcp, menemui merge sebagai satu alat, dan memanggilnya dengan kaedah kunci API yang sama seperti REST. Dokumentasi: MCP untuk pembangun.

MCP bukan katalog kedua. Ia ialah protokol penemuan dan seruan di atas operasi yang sama yang disenaraikan oleh OpenAPI. Jika sesuatu operasi tiada dalam MCP, itu pepijat pelayan, bukan perancangan produk yang berasingan. Gandingkan MCP dengan /llms.txt apabila anda mahukan indeks alat dalam bentuk prosa sebelum klien disambungkan.

CLI pdfx

pdf-core setempat:

pdfx merge a.pdf b.pdf -o merged.pdf

Atau pelayan yang sama yang digunakan oleh portal:

pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf

Mod setempat tidak pernah memuat naik; mod awan menghubungi URL asas anda dengan bentuk multipart yang sama seperti curl. Skill ejen pengekodan di dist/skills/pdf-toolbox/SKILL.md mendokumentasikan bentuk merge dan pipeline yang sama supaya ejen tidak mencipta OpenAPI kedua.

OCR melalui mana-mana klien ini masih memulangkan Markdown daripada /api/v1/misc/ocr-pdf, bukan lapisan teks tersembunyi. Fakta itu sebahagian daripada kontrak yang dikongsi: mengubah jenis pulangan dalam satu klien tanpa mengubah yang lain akan melanggar janji “operasi yang sama.” Operasi mampat kekal di /api/v1/misc/compress-pdf untuk pemampatan semula aliran; ia operasi yang berbeza daripada gabungan, tetapi boleh dicapai melalui empat cara yang sama.

Mengapa kesamaan penting

Jika gabungan melalui pelayar dan gabungan melalui API pernah menyimpang, automasi akan mengalami regresi secara senyap sementara halaman demo masih kelihatan baik. Satu operasi, empat cara akses, itulah intinya. Portal ialah klien untuk kemudahan, bukan pelaksanaan kedua bagi merge, compress, atau OCR.

Itulah juga sebabnya tiada cabang desktop: pokok antara muka yang kelima akan mencipta semula masalah hanyutan itu di bawah nama binari yang berbeza. Rangka yang lebih luas: Dibina untuk ejen AI, bukan hanya pelayar. Untuk keputusan tentang desktop, lihat Mengapa kami melangkau aplikasi desktop. Untuk menyediakan API dalam rangkaian anda, lihat Self-host.