Chuyển đến nội dung chính
PPDF123

PDF123 cho nhà phát triển: REST API, SDK, dòng lệnh và MCP

Nền tảng dành cho nhà phát triển của PDF123 cung cấp cùng 97 công cụ PDF qua bốn giao diện: REST API mô tả bằng OpenAPI, SDK TypeScript, dòng lệnh pdfx và máy chủ MCP cho AI agent. Gọi ẩn danh không cần tài khoản hay khóa API.

Trên trang này

Nên gọi PDF123 từ mã nguồn bằng cách nào?

Cả bốn giao diện đều gọi cùng các thao tác, nên một lần gộp tệp cho kết quả giống nhau ở mỗi giao diện. Hãy chọn theo nơi mã của bạn chạy.

Giao diệnPhù hợp vớiCài đặt hoặc địa chỉHướng dẫn
REST APIMọi ngôn ngữ, máy chủ, script shellhttps://pdf123.xyz/api/v1Tài liệu API
SDK TypeScriptMã Node, Bun và trình duyệt cần kiểu dữ liệunpm install @pdf123/sdkHướng dẫn SDK
Dòng lệnhTerminal, tác vụ CI, xử lý hàng loạt tệp cục bộnpm install -g @pdf123/cliHướng dẫn CLI
MCPAI agent như Claude Code, Claude Desktop và Cursornpx -y @pdf123/mcp hoặc https://pdf123.xyz/mcpHướng dẫn MCP

Hãy dùng REST API nếu mã của bạn không viết bằng TypeScript. Nếu có, hãy dùng SDK vì tùy chọn của từng công cụ có kiểu dữ liệu và được kiểm tra trước khi tải lên. Dùng dòng lệnh cho việc làm một lần và script shell. Dùng MCP khi muốn AI agent tự quyết định chạy công cụ nào.

Danh mục có 97 công cụ. Trong đó 58 công cụ có trang riêng trên website này, chẳng hạn Gộp PDF, Tách PDF và Nén PDF. Phần còn lại là các thao tác backend không có trang web, và tất cả đều dùng được trong SDK, dòng lệnh và MCP.

Làm sao chạy yêu cầu đầu tiên?

Gộp hai tệp bằng curl. Yêu cầu là một biểu mẫu multipart, mỗi tệp là một phần fileInput.

REST: merge two PDFsbash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -F [email protected] -F [email protected] \
  -o merged.pdf

Cùng thao tác gộp đó với SDK TypeScript:

SDK: merge two PDFsts
import { Pdf123Client } from "@pdf123/sdk";
import { readFileInput, saveResult } from "@pdf123/sdk/node";

const client = new Pdf123Client();
const result = await client.run("merge", {
  input: [await readFileInput("a.pdf"), await readFileInput("b.pdf")],
});
await saveResult(result, { output: "merged.pdf" });

Cùng thao tác gộp đó với dòng lệnh:

CLI: merge two PDFsbash
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf

Xác thực hoạt động thế nào?

Gọi ẩn danh vào API công khai không cần tài khoản và không cần khóa. Hãy gửi khóa API trong header X-API-KEY khi bạn muốn định danh lưu lượng của mình hoặc gọi endpoint MCP lưu trữ sẵn, vốn luôn yêu cầu khóa.

Đăng nhập để tạo khóa trong bảng bên dưới, rồi cất ở nơi an toàn.

Đang kiểm tra phiên của bạn…

Call the API with a keybash
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
  -H "X-API-KEY: <your-key>" \
  -F [email protected] -F [email protected] -o merged.pdf

SDK nhận khóa qua apiKey. Dòng lệnh và máy chủ MCP cục bộ đọc khóa từ biến môi trường PDFX_API_KEY.

Lưu ý

Trên máy chủ tự host, hãy đặt biến môi trường SECURITY_CUSTOMGLOBALAPIKEY để định nghĩa một khóa mà máy chủ chấp nhận. Xem Tự host.

Tài liệu tham chiếu API ở đâu?

REST API được ghi tài liệu dưới hai dạng. Swagger UI cho phép thử từng endpoint ngay trong trình duyệt. Tài liệu OpenAPI là nguồn đọc được bằng máy, dành cho các công cụ sinh client.

Mỗi thao tác là một yêu cầu POST dưới URL gốc https://pdf123.xyz/api/v1, được nhóm theo danh mục. Ví dụ, gộp là /general/merge-pdfs và nén là /misc/compress-pdf.

Làm sao nối nhiều công cụ trong một yêu cầu?

POST /api/v1/pipeline nhận các phần fileInput và một trường steps. Trường này là mảng JSON gồm các đối tượng có op và params tùy chọn. Mỗi bước nhận đầu ra của bước trước.

Merge, then compress, in one requestbash
curl -X POST https://pdf123.xyz/api/v1/pipeline \
  -F [email protected] -F [email protected] \
  -F 'steps=[{"op":"general/merge-pdfs"},{"op":"misc/compress-pdf"}]' \
  -o out.pdf

Làm sao thử lại yêu cầu một cách an toàn?

Hãy gửi header Idempotency-Key với bất kỳ thao tác nào. Nếu cùng yêu cầu đó được lặp lại trong 24 giờ, hệ thống trả về kết quả đầu tiên kèm header Idempotency-Replayed: true thay vì chạy lại. Dùng cùng một khóa cho một yêu cầu khác sẽ bị từ chối. Kết quả lớn hơn 32 MiB không được lưu, nên lặp lại yêu cầu như vậy sẽ nhận 409 và cần khóa mới.

Giới hạn dung lượng và tần suất là gì?

Giới hạnGiá trị
Dung lượng tệp trên website500 MB mỗi tệp
Một body yêu cầu API trực tiếp100 MiB, đã tính phần đóng gói multipart
Tải lên theo từng phầnSDK tự chuyển sang API tải lên khi tổng dung lượng vượt 95 MB

Phản hồi có các header X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Phản hồi có trạng thái 429 có thêm Retry-After. Hãy đọc các header này thay vì giả định một hạn mức cố định, vì máy chủ tự host đặt giới hạn riêng. Bài trên blog về giới hạn kích thước yêu cầu giải thích lỗi bạn nhận được khi body quá lớn.

Lỗi trông như thế nào?

Khi thất bại, API trả về application/problem+json với các trường type, title, status, detail, code, reason và hint. Hãy rẽ nhánh theo reason và dùng code làm dự phòng. Văn bản detail được viết cho con người và không bao giờ chứa đầu ra thô của công cụ. Toàn bộ mã nằm ở trang Mã lỗi.

Mã hoặc lý doTrạng thái HTTPÝ nghĩa
bad_request400Tham số hoặc body multipart không hợp lệ
password_required400PDF đã được mã hóa và không có mật khẩu nào được gửi
invalid_pdf400Tệp không phải PDF hoặc bị hỏng; hãy thử Sửa PDF
page_out_of_range400Trang được yêu cầu không tồn tại
not_found404Đường dẫn thao tác không xác định
rate_limited429Đã hết hạn mức; hãy chờ theo Retry-After

Nên gọi những công cụ nào trước?

Mười hai công cụ này đáp ứng phần lớn yêu cầu. Dùng trang công cụ để thử ngay trong trình duyệt.

Trang công cụEndpoint APILệnh CLIChức năng
Gộp/general/merge-pdfspdfx mergeGhép nhiều PDF thành một
Tách/general/split-pagespdfx splitChia một PDF thành các tệp riêng
Nén/misc/compress-pdfpdfx compressNén lại các luồng PDF để giảm dung lượng
Xoay/general/rotate-pdfpdfx rotateĐổi hướng trang
Bảo vệ/security/add-passwordpdfx protectMã hóa PDF bằng mật khẩu
Mở khóa/security/remove-passwordpdfx unlockGỡ bảo vệ bằng mật khẩu
Hình mờ/security/add-watermarkpdfx watermarkThêm hình mờ chữ hoặc ảnh
OCR/misc/ocr-pdfpdfx ocrĐọc PDF quét và trả về Markdown
PDF sang Markdown/convert/pdf/markdownpdfx pdf-to-markdownChuyển PDF thành Markdown
PDF sang Word/convert/pdf/wordpdfx convert-to-wordChuyển PDF thành tệp Word có thể chỉnh sửa
Thông tin tài liệu/security/get-info-on-pdfpdfx get-infoBáo cáo siêu dữ liệu, quyền, phông chữ và cấu trúc
Sửa/misc/repairpdfx repairDựng lại cấu trúc của PDF bị hỏng

Các endpoint tính từ https://pdf123.xyz/api/v1. Chạy pdfx list hoặc mở tài liệu OpenAPI để xem cả 97 công cụ.

Làm sao dùng PDF123 từ một AI agent?

Một agent có thể dùng các công cụ theo ba cách:

  • Kết nối một máy chủ MCP. Hướng dẫn MCP nói về máy chủ cục bộ @pdf123/mcp cho tệp trên máy bạn và endpoint lưu trữ sẵn tại https://pdf123.xyz/mcp.
  • Nạp một skill cho agent. Skill cho agent là các tệp SKILL.md dành cho Claude Code, Codex, Cursor và các công cụ tương tự: một skill cho cả danh mục và một skill cho từng công cụ.
  • Đọc chỉ mục của site. /llms.txt liệt kê công cụ, API và endpoint MCP dưới dạng văn bản thuần, còn /site.jsonld mô tả site bằng dữ liệu có cấu trúc.

Bài "Xây cho AI agent, không chỉ trình duyệt: API hoạt động thế nào" trên blog PDF123 giải thích cách REST API và MCP phối hợp với nhau.

Tôi có thể chạy PDF123 trên máy chủ của mình không?

Có. Backend là chương trình pdfx-server, chạy trong Docker. Hãy trỏ SDK, dòng lệnh hoặc máy chủ MCP tới nó bằng PDFX_API_BASE, và tệp của bạn sẽ ở lại trong mạng của bạn. Xem Tự host để biết cách thiết lập và Doanh nghiệp để biết các phương án hỗ trợ.

Câu hỏi thường gặp

API của PDF123 có miễn phí không?

Có, khi dùng ẩn danh. Gọi API công khai không cần tài khoản hay khóa. Phản hồi từ dịch vụ lưu trữ sẵn có kèm header giới hạn tần suất, nên client có thể giảm tốc trước khi nhận phản hồi 429.

Tôi có cần khóa API không?

Không cần với REST API, SDK và dòng lệnh khi bạn dùng site công khai. Cần với endpoint MCP lưu trữ sẵn tại /mcp, endpoint này trả 401 nếu thiếu header X-API-KEY. Bạn có thể tạo khóa ngay trên trang này sau khi đăng nhập.

Giới hạn dung lượng tệp là bao nhiêu?

Website nhận tệp tối đa 500 MB mỗi tệp. Body của một yêu cầu API trực tiếp có thể lên tới 100 MiB, tính cả phần đóng gói multipart. SDK tự động tải đầu vào lớn hơn lên theo từng phần khi tổng dung lượng vượt 95 MB.

Tôi có thể tự host API không?

Có. Hãy tự chạy máy chủ và đặt API base là địa chỉ của nó. SDK, dòng lệnh và máy chủ MCP cục bộ đều chấp nhận URL gốc tùy chỉnh.

Làm sao báo cáo lỗi?

Hãy sao chép các trường code, reason và detail từ phản hồi lỗi, kèm thời điểm gửi yêu cầu, rồi gửi qua trang liên hệ. Đừng gửi chính tệp PDF trừ khi bộ phận hỗ trợ yêu cầu.

Nên dùng SDK, dòng lệnh hay MCP?

Dùng SDK trong mã TypeScript, dòng lệnh cho script và xử lý hàng loạt tệp cục bộ, còn MCP khi AI agent chọn công cụ. Cả ba dùng chung một danh mục và một máy chủ, nên bạn có thể kết hợp chúng.