跳到主要内容
PPDF123

开发者使用 PDF123:REST API、SDK、命令行与 MCP

PDF123 开发者平台通过四种接口提供同一套 97 个 PDF 工具:由 OpenAPI 描述的 REST API、TypeScript SDK、pdfx 命令行,以及面向 AI 智能体的 MCP 服务器。匿名调用不需要账号或 API 密钥。

本页内容

在代码中该用哪种方式调用 PDF123?

四种接口调用的是同一批操作,因此同一次合并在每种接口下结果一致。请根据代码的运行环境选择。

接口适用场景安装方式或地址指南
REST API任意语言、服务器、Shell 脚本https://pdf123.xyz/api/v1API 参考
TypeScript SDK需要类型支持的 Node、Bun 和浏览器代码npm install @pdf123/sdkSDK 指南
命令行终端、CI 任务、批量处理本地文件npm install -g @pdf123/cliCLI 指南
MCPClaude Code、Claude Desktop、Cursor 等 AI 智能体npx -y @pdf123/mcp 或 https://pdf123.xyz/mcpMCP 指南

如果代码不是用 TypeScript 写的,请使用 REST API。如果是,请使用 SDK,因为工具选项带有类型,并会在上传前完成检查。一次性任务和 Shell 脚本适合用命令行。需要由 AI 智能体决定运行哪个工具时,请使用 MCP。

目录共有 97 个工具,其中 58 个在本网站上有专属页面,例如合并 PDF、拆分 PDF和压缩 PDF。其余是没有网页的后端操作,SDK、命令行和 MCP 中都可以使用全部工具。

如何发出第一个请求?

用 curl 合并两个文件。请求是 multipart 表单,每个文件对应一个 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

用 TypeScript SDK 完成同样的合并:

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" });

用命令行完成同样的合并:

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

如何进行身份验证?

匿名调用公共 API 不需要账号,也不需要密钥。如果想标识自己的流量,或要调用必须使用密钥的托管 MCP 端点,请在 X-API-KEY 请求头中发送 API 密钥。

登录后可在下方面板中创建密钥,并妥善保管。

正在检查登录状态…

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 通过 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。每一步接收上一步的输出。

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

如何安全地重试请求?

在任意操作上发送 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_request400参数或 multipart 正文无效
password_required400PDF 已加密,但没有发送密码
invalid_pdf400文件不是 PDF 或已损坏;可尝试修复 PDF
page_out_of_range400请求的页面不存在
not_found404操作路径未知
rate_limited429配额已用完;请等待 Retry-After 指定的时间

可以先调用哪些工具?

这十二个工具覆盖了大多数请求。可以在工具页面中直接在浏览器里试用。

工具页面API 端点CLI 命令功能
合并/general/merge-pdfspdfx merge将多个 PDF 合并为一个
拆分/general/split-pagespdfx split将一个 PDF 拆分为多个文件
压缩/misc/compress-pdfpdfx compress重新压缩 PDF 数据流以减小体积
旋转/general/rotate-pdfpdfx rotate更改页面方向
加密保护/security/add-passwordpdfx protect用密码加密 PDF
解锁/security/remove-passwordpdfx unlock移除密码保护
水印/security/add-watermarkpdfx watermark添加文字或图片水印
OCR/misc/ocr-pdfpdfx ocr识别扫描版 PDF 并返回 Markdown
PDF 转 Markdown/convert/pdf/markdownpdfx pdf-to-markdown将 PDF 转换为 Markdown
PDF 转 Word/convert/pdf/wordpdfx convert-to-word将 PDF 转换为可编辑的 Word 文件
文档信息/security/get-info-on-pdfpdfx get-info报告元数据、权限、字体和结构
修复/misc/repairpdfx 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。三者使用同一个目录和同一台服务器,因此可以组合使用。