在代码中该用哪种方式调用 PDF123?
四种接口调用的是同一批操作,因此同一次合并在每种接口下结果一致。请根据代码的运行环境选择。
| 接口 | 适用场景 | 安装方式或地址 | 指南 |
|---|---|---|---|
| REST API | 任意语言、服务器、Shell 脚本 | https://pdf123.xyz/api/v1 | API 参考 |
| TypeScript SDK | 需要类型支持的 Node、Bun 和浏览器代码 | npm install @pdf123/sdk | SDK 指南 |
| 命令行 | 终端、CI 任务、批量处理本地文件 | npm install -g @pdf123/cli | CLI 指南 |
| MCP | Claude Code、Claude Desktop、Cursor 等 AI 智能体 | npx -y @pdf123/mcp 或 https://pdf123.xyz/mcp | MCP 指南 |
如果代码不是用 TypeScript 写的,请使用 REST API。如果是,请使用 SDK,因为工具选项带有类型,并会在上传前完成检查。一次性任务和 Shell 脚本适合用命令行。需要由 AI 智能体决定运行哪个工具时,请使用 MCP。
目录共有 97 个工具,其中 58 个在本网站上有专属页面,例如合并 PDF、拆分 PDF和压缩 PDF。其余是没有网页的后端操作,SDK、命令行和 MCP 中都可以使用全部工具。
如何发出第一个请求?
用 curl 合并两个文件。请求是 multipart 表单,每个文件对应一个 fileInput 部分。
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdf用 TypeScript SDK 完成同样的合并:
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" });用命令行完成同样的合并:
npx @pdf123/cli merge a.pdf b.pdf -o merged.pdf如何进行身份验证?
匿名调用公共 API 不需要账号,也不需要密钥。如果想标识自己的流量,或要调用必须使用密钥的托管 MCP 端点,请在 X-API-KEY 请求头中发送 API 密钥。
登录后可在下方面板中创建密钥,并妥善保管。
正在检查登录状态…
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 通过 apiKey 接收密钥。命令行和本地 MCP 服务器从环境变量 PDFX_API_KEY 读取密钥。
注意
在自托管服务器上,设置环境变量 SECURITY_CUSTOMGLOBALAPIKEY 即可定义服务器接受的唯一密钥。参见自托管。
API 参考在哪里?
REST API 提供两种文档形式。Swagger UI 可以直接在浏览器中试用每个端点。OpenAPI 文档是机器可读的来源,供客户端生成器使用。
每个操作都是基础 URL https://pdf123.xyz/api/v1 下的 POST 请求,并按类别分组。例如,合并是 /general/merge-pdfs,压缩是 /misc/compress-pdf。
如何在一次请求中串联多个工具?
POST /api/v1/pipeline 接收若干 fileInput 部分和一个 steps 字段。该字段是 JSON 数组,其中每个对象包含 op,以及可选的 params。每一步接收上一步的输出。
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如何安全地重试请求?
在任意操作上发送 Idempotency-Key 请求头。24 小时内重复发送同一请求时,不会再次执行,而是返回第一次的结果,并附带响应头 Idempotency-Replayed: true。对不同的请求使用同一个密钥会被拒绝。大于 32 MiB 的结果不会被存储,因此重复此类请求会返回 409,需要换用新的密钥。
大小和速率有哪些限制?
| 限制 | 数值 |
|---|---|
| 网站上的文件大小 | 每个文件 500 MB |
| 一次直接 API 请求的正文 | 100 MiB,包含 multipart 封装 |
| 分块上传 | 总大小超过 95 MB 时,SDK 会自动切换到上传 API |
响应带有 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 响应头。状态码为 429 的响应还会附带 Retry-After。请读取这些响应头,不要假定固定配额,因为自托管服务器有自己的限制。关于请求体过大时返回的错误,可参阅博客文章请求大小限制。
错误是什么样子的?
失败时返回 application/problem+json,包含字段 type、title、status、detail、code、reason 和 hint。请优先根据 reason 分支处理,并回退到 code。detail 文本面向用户编写,不包含原始的工具输出。所有错误码都列在错误码页面。
| 错误码或原因 | HTTP 状态 | 含义 |
|---|---|---|
bad_request | 400 | 参数或 multipart 正文无效 |
password_required | 400 | PDF 已加密,但没有发送密码 |
invalid_pdf | 400 | 文件不是 PDF 或已损坏;可尝试修复 PDF |
page_out_of_range | 400 | 请求的页面不存在 |
not_found | 404 | 操作路径未知 |
rate_limited | 429 | 配额已用完;请等待 Retry-After 指定的时间 |
可以先调用哪些工具?
这十二个工具覆盖了大多数请求。可以在工具页面中直接在浏览器里试用。
| 工具页面 | API 端点 | CLI 命令 | 功能 |
|---|---|---|---|
| 合并 | /general/merge-pdfs | pdfx merge | 将多个 PDF 合并为一个 |
| 拆分 | /general/split-pages | pdfx split | 将一个 PDF 拆分为多个文件 |
| 压缩 | /misc/compress-pdf | pdfx compress | 重新压缩 PDF 数据流以减小体积 |
| 旋转 | /general/rotate-pdf | pdfx rotate | 更改页面方向 |
| 加密保护 | /security/add-password | pdfx protect | 用密码加密 PDF |
| 解锁 | /security/remove-password | pdfx unlock | 移除密码保护 |
| 水印 | /security/add-watermark | pdfx watermark | 添加文字或图片水印 |
| OCR | /misc/ocr-pdf | pdfx ocr | 识别扫描版 PDF 并返回 Markdown |
| PDF 转 Markdown | /convert/pdf/markdown | pdfx pdf-to-markdown | 将 PDF 转换为 Markdown |
| PDF 转 Word | /convert/pdf/word | pdfx convert-to-word | 将 PDF 转换为可编辑的 Word 文件 |
| 文档信息 | /security/get-info-on-pdf | pdfx get-info | 报告元数据、权限、字体和结构 |
| 修复 | /misc/repair | pdfx repair | 重建损坏 PDF 的结构 |
端点均相对于 https://pdf123.xyz/api/v1。运行 pdfx list 或打开 OpenAPI 文档,可以查看全部 97 个工具。
如何在 AI 智能体中使用 PDF123?
智能体可以通过三种方式使用这些工具:
- 连接 MCP 服务器。MCP 指南介绍了用于本机文件的本地
@pdf123/mcp服务器,以及位于https://pdf123.xyz/mcp的托管端点。 - 加载智能体技能。智能体技能是面向 Claude Code、Codex、Cursor 等工具的
SKILL.md文件,其中一个对应整个目录,另外每个工具各有一个。 - 阅读站点索引。/llms.txt 以纯文本列出工具、API 和 MCP 端点,
/site.jsonld则以结构化数据描述本站。
PDF123 博客上的文章《为 AI Agent 而建,不只为浏览器:API 怎么用》介绍了 REST API 与 MCP 如何配合使用。
可以在自己的服务器上运行 PDF123 吗?
可以。后端是 pdfx-server 程序,在 Docker 中运行。通过 PDFX_API_BASE 让 SDK、命令行或 MCP 服务器指向它,文件就会留在你的网络内。部署方法见自托管,支持方案见企业版。
常见问题
PDF123 的 API 免费吗?
匿名使用免费。调用公共 API 不需要账号或密钥。托管服务的响应包含速率限制响应头,因此客户端可以在收到 429 响应之前放慢请求速度。
需要 API 密钥吗?
使用公共站点时,REST API、SDK 和命令行都不需要。托管 MCP 端点 /mcp 需要,没有 X-API-KEY 请求头时它会返回 401。登录后可以在本页创建密钥。
文件大小有什么限制?
网站接受每个最大 500 MB 的文件。一次直接 API 请求的正文最大可达 100 MiB,包含 multipart 封装。输入总大小超过 95 MB 后,SDK 会自动分块上传更大的输入。
可以自托管 API 吗?
可以。自行运行服务器,并把 API 基础地址设置为它的地址即可。SDK、命令行和本地 MCP 服务器都支持自定义基础 URL。
如何报告错误?
请从问题响应中复制 code、reason 和 detail 字段,并附上请求的时间,通过联系页面发送给我们。除非支持人员要求,否则请不要发送 PDF 本身。
应该用 SDK、命令行还是 MCP?
在 TypeScript 代码中使用 SDK,处理脚本和本地文件批量任务时使用命令行,由 AI 智能体选择工具时使用 MCP。三者使用同一个目录和同一台服务器,因此可以组合使用。