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.

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 trả Markdown (text/markdown) từ /api/v1/misc/ocr-pdf, không phải PDF có lớp chữ ẩn. Agent kỳ vọng điểm cuối đó cho ra PDF tìm kiếm được sẽ xử lý nhầm tệp tải về; hợp đồng ở đây là trích xuất văn bản, không phải viết lại kiểu OCRmyPDF.

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 chạy được pdf-core ngay trên máy hoặc --cloud trỏ tới một base URL. Skill coding-agent trong dist/skills/pdf-toolbox/SKILL.md ghi lại hình dạng curl của merge và pipeline để agent không tự đặt 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.