Dibangun untuk agen AI, bukan hanya browser: bagaimana API bekerja

Tab browser tetap bisa dipakai: pilih alat, unggah berkas, unduh hasilnya. Agen dan skrip memanggil operasi yang sama tanpa membuka antarmuka. Kedua jalur itu menuju katalog yang sama.

Setiap halaman alat juga merupakan titik akhir

Merge, split, compress, OCR, convert: setiap alat di katalog dipetakan ke /api/v1/…. Buka halaman alat dan gulir ke Call this from code untuk melihat contoh curl yang disusun dari parameter asli alat tersebut, bukan templat generik. Panggilan anonim tidak memerlukan akun maupun API key di situs publik; prefiks anonimnya adalah /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/, dan /api/v1/filter/.

Contoh untuk merge cukup konkret:

curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o merged.pdf

Spesifikasi OpenAPI tersedia di /v1/openapi.json. Pekerjaan berlapis memakai POST /api/v1/pipeline dengan daftar steps yang berurutan. Sertakan Idempotency-Key bila percobaan ulang tidak boleh menjalankan dua kali tugas yang mengubah data. Respons dari layanan hosted menyertakan X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset; saat menerima HTTP 429, bacalah Retry-After (pembatasan laju untuk pemanggil anonim).

OCR melalui katalog yang sama mengembalikan Markdown (text/markdown) dari /api/v1/misc/ocr-pdf, bukan PDF dengan lapisan teks tersembunyi. Agen yang mengira titik akhir itu menghasilkan PDF yang bisa dicari akan salah menangani unduhannya; kontraknya adalah ekstraksi teks untuk pipeline, bukan penulisan ulang bergaya OCRmyPDF.

MCP untuk klien yang memahaminya

MCP (Model Context Protocol) memungkinkan klien agen menemukan dan memanggil alat sebagai fungsi, tanpa perlu mengikis dokumentasi. Situs ini menyediakan server MCP di /mcp di samping REST API, sehingga klien yang kompatibel cukup tersambung sekali dan langsung mendapat seluruh katalog.

MCP dan REST berbagi aturan autentikasi: anonim selama prefiks alat mengizinkannya, dan API key untuk otomasi yang stabil maupun untuk server self-host yang dibatasi. Mengarahkan agen ke /mcp bukan produk yang berbeda dari mengarahkan curl ke /api/v1/…. Dokumentasi: MCP untuk pengembang.

Galat berbentuk struktur, bukan prosa

Kegagalan mengembalikan application/problem+json (gaya RFC 7807), bukan 500 kosong atau pesan "something went wrong." Setiap payload membawa kode yang stabil (rate_limited, bad_request, invalid_document, missing_dependency, dan kode sejenis), petunjuk yang mudah dibaca, dan sering kali langkah berikutnya. Manusia bisa memindainya sekilas; agen bisa memutuskan untuk mencoba ulang, mengganti berkas, atau berhenti tanpa ada orang yang harus mengurai jejak tumpukan.

Struktur seperti itu lebih penting daripada halaman galat HTML yang ramah ketika pemanggilnya adalah sebuah skrip. Referensi: Galat API di Developers.

llms.txt untuk perkakas, bukan peringkat

/llms.txt adalah indeks teks biasa berisi setiap alat (nama, ringkasan, URL), yang dihasilkan dari katalog yang sama dengan yang menggerakkan situs. Agen coding dan alat dokumentasi bisa membacanya seperti README. Berkas ini bukan pengungkit peringkat Google: mesin pencari mengabaikan /llms.txt (sumber: panduan Google untuk optimasi AI). Karena dihasilkan otomatis, isinya tidak bisa diam-diam basi seperti berkas yang disunting manual.

CLI dan skill memakai bentuk yang sama

pdfx bisa menjalankan pdf-core secara lokal atau --cloud terhadap sebuah base URL. Skill untuk agen coding di dist/skills/pdf-toolbox/SKILL.md mendokumentasikan bentuk curl untuk merge dan pipeline agar agen tidak menciptakan kontrak kedua. Empat klien, satu katalog: Operasi yang sama, empat klien.

Jalur browser tidak berubah

Menjatuhkan berkas ke tab tetap bekerja seperti sebelumnya. Permukaan tambahannya adalah titik akhir yang sama untuk agen, skrip, atau CI: pemrosesan yang sama, tanpa manusia di tengahnya. Self-host menyimpan permukaan itu di jaringan Anda (Self-host); versi hosted tetap menjadi jalur uji coba anonim.

Referensi API: Swagger. Dasar untuk kedua jalur: Help dan Developers.