Product4 phút đọc

Xây cho AI agent, không chỉ trình duyệt: API hoạt động thế nào

Mọi công cụ trong danh mục đều là điểm cuối REST dưới /api/v1/, kèm MCP tại /mcp. Gọi ẩn danh không cần tài khoản hay API key; lỗi trả problem+json kiểu RFC 7807.

By the PDF123 team · Updated 2026-10-09
Xây cho AI agent, không chỉ trình duyệt: API hoạt động thế nào

Một tab trình duyệt vẫn chạy được: chọn công cụ, tải tệp lên, tải kết quả về. Agent và script gọi cùng những thao tác đó mà không cần mở giao diện; cả hai đường vào cùng một danh mục.

Diagram showing a browser click and an agent/script call both reaching the same API endpoints and returning the same result

Mọi trang công cụ cũng là một điểm cuối

Ghép PDF, tách, nén, OCR, chuyển đổi: mọi công cụ trong danh mục đều ánh xạ tới /api/v1/…. Mở trang công cụ, cuộn tới mục Call this from code để xem ví dụ curl dựng từ chính tham số thật của công cụ đó, không phải mẫu chung. Gọi ẩn danh không cần tài khoản lẫn API key; các tiền tố ẩn danh gồm /api/v1/general/, /api/v1/misc/, /api/v1/security/, /api/v1/convert/ và /api/v1/filter/.

Ví dụ ghép tệp:

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

OpenAPI nằm tại /v1/openapi.json. Việc nhiều bước dùng POST /api/v1/pipeline với danh sách steps có thứ tự. Gửi Idempotency-Key khi lần thử lại không được chạy lặp tác vụ có thay đổi dữ liệu. Phản hồi hosted công bố X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset; khi gặp HTTP 429, đọc Retry-After (giới hạn tần suất ẩn danh).

OCR qua cùng danh mục mặc định trả Markdown (text/markdown) từ /api/v1/misc/ocr-pdf. Gửi outputFormat=pdf thì cùng điểm cuối đó trả về một PDF tìm kiếm được (application/pdf, tối đa 50 trang, nhận dạng bằng Tesseract). Agent nên đọc Content-Type của phản hồi thay vì giả định tệp tải về là văn bản, vì hai đầu ra đến từ các engine khác nhau với giới hạn khác nhau.

MCP cho những client hiểu giao thức này

MCP (Model Context Protocol) cho client agent khám phá và gọi công cụ như hàm, thay vì tự đọc tài liệu. Site mở MCP server tại /mcp bên cạnh REST API, nên client tương thích chỉ kết nối một lần là có cả danh mục.

MCP và REST chia sẻ cùng kỳ vọng xác thực: ẩn danh ở nơi tiền tố công cụ cho phép; API key cho tự động hóa ổn định và server self-host có kiểm soát. Trỏ agent vào /mcp không phải sản phẩm khác với trỏ curl vào /api/v1/…. Tài liệu: MCP cho nhà phát triển.

Lỗi có cấu trúc, không phải văn xuôi

Khi thất bại, server trả application/problem+json (kiểu RFC 7807), không phải mã 500 trơ trọi hay câu "something went wrong". Mỗi payload mang một mã ổn định (rate_limited, bad_request, invalid_document, missing_dependency và các mã tương tự), một gợi ý đọc được, và thường cả bước tiếp theo. Người đọc lướt là hiểu; agent có thể tự quyết thử lại, đổi tệp hay dừng mà không cần ai phân tích vết ngăn xếp.

Khi bên gọi là script, cấu trúc đó quan trọng hơn một trang lỗi HTML thân thiện. Tham chiếu: Lỗi cho nhà phát triển.

llms.txt dành cho công cụ, không phải để lên hạng

/llms.txt là mục lục văn bản thuần của mọi công cụ (tên, mô tả ngắn, URL), sinh từ chính danh mục của site. Agent lập trình và công cụ tài liệu đọc nó như README. Nó không phải đòn bẩy xếp hạng Google: Search bỏ qua /llms.txt (nguồn: hướng dẫn tối ưu hóa AI của Google). Vì được sinh tự động, nó không thể âm thầm lỗi thời như tệp sửa tay.

CLI và skill chung một hình dạng

pdfx là client của chính bề mặt REST đó, nhắm vào một base URL với API key tùy chọn, nên nó gửi yêu cầu multipart mà curl sẽ gửi thay vì phơi ra một danh mục thứ hai. Skill đã công bố tại /skills/pdf123.md ghi lại các hình dạng merge và pipeline để agent cũng không tự đặt ra hợp đồng thứ hai. Bốn client, một danh mục: Cùng thao tác, bốn client.

Đường trình duyệt không đổi

Thả tệp vào tab vẫn như trước. Phần mở rộng là chính những điểm cuối đó cho agent, script hoặc CI: cùng cách xử lý, không cần người ở giữa. Self-host giữ phần mở rộng ấy trong mạng của bạn (Self-host); bản hosted vẫn là đường dùng thử ẩn danh.

Tham chiếu API: Swagger. Kiến thức cơ bản cho cả hai đường: Trợ giúp và Nhà phát triển.

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool