Dibina untuk Ejen AI, Bukan Hanya Pelayar: Cara API Berfungsi
Setiap alat katalog ialah laluan REST di /api/v1/ serta MCP di /mcp. Panggilan tanpa nama tidak perlukan akaun atau kunci API. Ralat guna problem+json RFC 7807.
Tab pelayar masih berfungsi seperti biasa: pilih alat, muat naik fail, muat turun hasilnya. Ejen dan skrip memanggil operasi yang sama tanpa membuka antara muka pengguna. Kedua-dua laluan menuju ke katalog yang sama.
Setiap halaman alat juga merupakan laluan
Gabungkan PDF, split, compress, OCR, convert: setiap alat dalam katalog dipetakan kepada /api/v1/…. Buka halaman alat dan tatal ke Call this from code untuk melihat contoh curl yang dibina daripada parameter sebenar alat itu, bukan templat generik. Panggilan tanpa nama tidak memerlukan akaun dan tidak memerlukan kunci API di tapak awam; awalan tanpa nama ialah /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/, dan /api/v1/filter/.
Contoh merge adalah konkrit:
curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
-F "[email protected]" \
-F "[email protected]" \
-o merged.pdf
OpenAPI terletak di /v1/openapi.json. Kerja berbilang langkah menggunakan POST /api/v1/pipeline dengan senarai steps yang tersusun. Hantar Idempotency-Key apabila cubaan semula tidak boleh menjalankan semula tugas yang mengubah keadaan. Respons yang dihoskan menyertakan X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset; apabila menerima HTTP 429, baca Retry-After (had kadar tanpa nama).
OCR melalui katalog yang sama memulangkan Markdown (text/markdown) daripada /api/v1/misc/ocr-pdf, bukan PDF dengan lapisan teks tersembunyi. Ejen yang menjangkakan PDF boleh cari daripada laluan itu akan tersalah mengendalikan muat turun tersebut; kontraknya ialah pengekstrakan teks untuk pipeline, bukan penulisan semula gaya OCRmyPDF.
MCP untuk klien yang menggunakannya
MCP (Model Context Protocol) membolehkan klien ejen menemui dan memanggil alat sebagai fungsi, tanpa perlu mengikis dokumentasi. Tapak ini menyediakan pelayan MCP di /mcp bersebelahan REST API, jadi klien yang serasi hanya perlu menyambung sekali untuk mendapatkan katalog penuh.
MCP dan REST berkongsi jangkaan pengesahan yang sama: tanpa nama jika awalan alat membenarkannya; kunci API untuk automasi yang stabil dan untuk pelayan self-host yang dikawal. Mengarahkan ejen ke /mcp bukanlah produk yang berbeza daripada mengarahkan curl ke /api/v1/…. Dokumentasi: MCP untuk pembangun.
Ralat berstruktur, bukan prosa
Kegagalan memulangkan application/problem+json (gaya RFC 7807), bukan 500 kosong atau "something went wrong." Setiap muatan mempunyai kod yang stabil (rate_limited, bad_request, invalid_document, missing_dependency, dan yang seumpamanya), petunjuk yang mudah dibaca, dan selalunya langkah seterusnya. Manusia boleh membacanya sekilas; ejen boleh memutuskan untuk cuba semula, menukar fail, atau berhenti tanpa perlu ada orang menghurai jejak tindanan.
Struktur itu lebih penting daripada halaman ralat HTML yang mesra apabila pemanggilnya ialah skrip. Rujukan: Ralat API.
llms.txt untuk peralatan, bukan kedudukan carian
/llms.txt ialah indeks teks biasa bagi setiap alat (nama, keterangan ringkas, URL), dijana daripada katalog yang sama yang menggerakkan tapak ini. Ejen pengekodan dan alat dokumentasi boleh membacanya seperti README. Ia bukan tuas kedudukan Google: Search mengabaikan /llms.txt (sumber: panduan Google untuk pengoptimuman AI). Kerana ia dijana secara automatik, ia tidak boleh menjadi basi secara senyap seperti fail yang disunting dengan tangan.
CLI dan skill berkongsi bentuk yang sama
pdfx boleh menjalankan pdf-core secara setempat atau --cloud terhadap URL asas. Skill ejen pengekodan di dist/skills/pdf-toolbox/SKILL.md mendokumentasikan bentuk curl untuk merge dan pipeline supaya ejen tidak mencipta kontrak kedua. Empat klien, satu katalog: Operasi sama, empat klien.
Laluan pelayar tidak berubah
Melepaskan fail ke dalam tab masih berfungsi seperti biasa. Permukaan tambahannya ialah laluan yang sama untuk ejen, skrip, atau CI: pemprosesan yang sama, tanpa manusia di tengah. Self-host mengekalkan permukaan itu dalam rangkaian anda (Self-host); yang dihoskan kekal sebagai laluan percubaan tanpa nama.
Rujukan API: Swagger. Asas untuk kedua-dua laluan: Bantuan dan Pembangun.