PPDF123
Product3 menit baca

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

Setiap alat di katalog tersedia sebagai titik akhir REST di bawah /api/v1/ dan lewat MCP di /mcp, dapat dipanggil tanpa akun, dan mengembalikan galat RFC 7807.

By the PDF123 team Β· Updated 2026-10-09
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.

Diagram yang menunjukkan klik di browser dan panggilan agen/skrip sama-sama mencapai titik akhir API yang sama dan mengembalikan hasil 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 secara default. Kirim outputFormat=pdf dan titik akhir yang sama mengembalikan PDF yang bisa dicari (application/pdf, hingga 50 halaman, dikenali dengan Tesseract). Agen sebaiknya membaca Content-Type respons, bukan mengira unduhannya berupa teks, karena kedua keluaran itu berasal dari mesin yang berbeda dengan batas yang berbeda.

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 adalah klien bagi permukaan REST yang sama, diarahkan ke base URL dengan API key opsional, sehingga ia mengirim permintaan multipart yang akan dikirim curl alih-alih memaparkan katalog kedua. Skill yang diterbitkan di /skills/pdf123.md mendokumentasikan bentuk merge dan pipeline agar agen juga 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.

Open tool
Process in the browser β€” no watermark, files removed after the job.
Open tool