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ện | Phù hợp với | Cài đặt hoặc địa chỉ | Hướng dẫn |
|---|---|---|---|
| REST API | Mọi ngôn ngữ, máy chủ, script shell | https://pdf123.xyz/api/v1 | Tài liệu API |
| SDK TypeScript | Mã Node, Bun và trình duyệt cần kiểu dữ liệu | npm install @pdf123/sdk | Hướng dẫn SDK |
| Dòng lệnh | Terminal, tác vụ CI, xử lý hàng loạt tệp cục bộ | npm install -g @pdf123/cli | Hướng dẫn CLI |
| MCP | AI agent như Claude Code, Claude Desktop và Cursor | npx -y @pdf123/mcp hoặc https://pdf123.xyz/mcp | Hướ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.
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdfCùng thao tác gộp đó với SDK TypeScript:
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:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdfXá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…
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.pdfSDK 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.
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.pdfLà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ạn | Giá trị |
|---|---|
| Dung lượng tệp trên website | 500 MB mỗi tệp |
| Một body yêu cầu API trực tiếp | 100 MiB, đã tính phần đóng gói multipart |
| Tải lên theo từng phần | SDK 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ý do | Trạng thái HTTP | Ý nghĩa |
|---|---|---|
bad_request | 400 | Tham số hoặc body multipart không hợp lệ |
password_required | 400 | PDF đã được mã hóa và không có mật khẩu nào được gửi |
invalid_pdf | 400 | Tệp không phải PDF hoặc bị hỏng; hãy thử Sửa PDF |
page_out_of_range | 400 | Trang được yêu cầu không tồn tại |
not_found | 404 | Đường dẫn thao tác không xác định |
rate_limited | 429 | Đã 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 API | Lệnh CLI | Chức năng |
|---|---|---|---|
| Gộp | /general/merge-pdfs | pdfx merge | Ghép nhiều PDF thành một |
| Tách | /general/split-pages | pdfx split | Chia một PDF thành các tệp riêng |
| Nén | /misc/compress-pdf | pdfx compress | Nén lại các luồng PDF để giảm dung lượng |
| Xoay | /general/rotate-pdf | pdfx rotate | Đổi hướng trang |
| Bảo vệ | /security/add-password | pdfx protect | Mã hóa PDF bằng mật khẩu |
| Mở khóa | /security/remove-password | pdfx unlock | Gỡ bảo vệ bằng mật khẩu |
| Hình mờ | /security/add-watermark | pdfx watermark | Thêm hình mờ chữ hoặc ảnh |
| OCR | /misc/ocr-pdf | pdfx ocr | Đọc PDF quét và trả về Markdown |
| PDF sang Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | Chuyển PDF thành Markdown |
| PDF sang Word | /convert/pdf/word | pdfx convert-to-word | Chuyển PDF thành tệp Word có thể chỉnh sửa |
| Thông tin tài liệu | /security/get-info-on-pdf | pdfx get-info | Báo cáo siêu dữ liệu, quyền, phông chữ và cấu trúc |
| Sửa | /misc/repair | pdfx repair | Dự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/mcpcho tệp trên máy bạn và endpoint lưu trữ sẵn tạihttps://pdf123.xyz/mcp. - Nạp một skill cho agent. Skill cho agent là các tệp
SKILL.mddà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.jsonldmô 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.