Cùng một thao tác, bốn client: trình duyệt, curl, MCP, pdfx

Bốn client trông như bốn sản phẩm. Chúng dùng chung một danh mục. Lấy Merge làm tác vụ cụ thể: ghép các PDF theo thứ tự tải lên mà không raster hóa trang thành ảnh. Khuôn mẫu đó đúng cho mọi công cụ khác trong danh mục (compress, OCR, convert và phần còn lại): một op id, bốn cách gọi.

Trình duyệt

Mở /merge, thêm tệp theo thứ tự bạn muốn, bấm Process, tải xuống. Không cần tài khoản cho công cụ trong danh mục. Khối “Call this from code” trên trang dựng curl từ đúng các trường mà form gửi, nên giao diện và hợp đồng HTTP luôn khớp nhau.

Khối đó không phải văn bản marketing. Nó sinh từ chính định nghĩa công cụ mà portal dùng cho form, nên đổi tên một tham số thì cả hai nơi cùng đổi. Nếu form nhận sortType=byFileName tùy chọn, ví dụ curl cũng mang cùng trường đó.

curl / REST

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

Gọi ẩn danh vào danh mục không cần key. Key từ Nhà phát triển cho tự động hóa một danh tính ổn định (và server self-host một cổng kiểm soát). OpenAPI ở /v1/openapi.json.

Với tác vụ nhiều bước, POST /api/v1/pipeline nhận các op có thứ tự trong trường steps (ví dụ merge, rồi watermark, rồi compress). Gửi Idempotency-Key khi các lần thử lại không được chạy lặp công việc; một replay thành công có thể trả về kèm Idempotency-Replayed. Thất bại dùng application/problem+json với các mã ổn định như rate_limited và bad_request (Lỗi cho nhà phát triển).

Phản hồi hosted cũng công bố X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset; HTTP 429 kèm Retry-After. Hãy coi những tiêu đề đó là ngân sách sống, không phải con số nhớ từ một bài blog (giới hạn tần suất ẩn danh).

MCP

Những agent hiểu Model Context Protocol kết nối tới /mcp, khám phá merge như một công cụ, và gọi nó với cùng câu chuyện API key như REST. Tài liệu: MCP cho nhà phát triển.

MCP không phải một danh mục thứ hai. Nó là một giao thức khám phá và gọi trên đúng những thao tác mà OpenAPI liệt kê. Nếu một op thiếu trong MCP, đó là bug server, không phải lộ trình sản phẩm riêng. Hãy ghép MCP với /llms.txt khi muốn một mục lục văn xuôi về công cụ trước khi client kết nối.

CLI pdfx

pdf-core cục bộ:

pdfx merge a.pdf b.pdf -o merged.pdf

Hoặc chính server mà portal dùng:

pdfx --cloud --api-base "$API_BASE" --api-key "$KEY" merge a.pdf b.pdf -o merged.pdf

Chế độ cục bộ không bao giờ tải lên; chế độ cloud đánh base URL của bạn với cùng hình dạng multipart như curl. Skill dành cho coding-agent trong dist/skills/pdf-toolbox/SKILL.md ghi lại cùng hình dạng merge và pipeline để agent không tự đặt ra một OpenAPI thứ hai.

OCR qua bất kỳ client nào vẫn trả Markdown từ /api/v1/misc/ocr-pdf, không phải một lớp chữ ẩn. Sự thật đó là một phần của hợp đồng chung: đổi kiểu trả về ở một client mà không đổi ở các client khác sẽ phá lời hứa “cùng một op”. Compress vẫn nằm ở /api/v1/misc/compress-pdf cho việc nén lại luồng; đó là một op khác với merge, nhưng vẫn chạm được bằng bốn cách như nhau.

Vì sao sự giống nhau quan trọng

Nếu merge trên trình duyệt và merge qua API lệch nhau, tự động hóa sẽ lặng lẽ thoái lui trong khi trang demo vẫn trông ổn. Một op, bốn cách chạm, chính là điểm mấu chốt. Portal là client tiện lợi, không phải bản triển khai thứ hai của merge, compress hay OCR.

Đó cũng là lý do không có bản fork desktop: một cây giao diện thứ năm sẽ tái tạo đúng vấn đề lệch hướng dưới một cái tên binary khác. Bối cảnh rộng hơn: Xây cho AI agent, không chỉ trình duyệt. Về quyết định desktop, xem Vì sao chúng tôi bỏ qua ứng dụng desktop. Để dựng API trên mạng của bạn, xem Self-host.