不用 API Key 的免费 PDF API：匿名调用能做到什么
PDF123 的 REST API 不需要 API Key 和账号。用 curl 合并、压缩 PDF，附大小限制、错误响应的格式，以及收到 HTTP 429 时客户端该怎么做。
有。PDF123 的 REST API 不需要 API Key，也不需要账号：测试时，用最普通的 curl 先后调用合并 PDF和压缩 PDF的端点，没带 X-API-KEY 请求头，两次都返回 HTTP 200 和一个 PDF。限制一次调用的是它的大小，以及分块上传同时开了多少个，与调用者是谁无关：一次请求的请求体最多 100 MiB，每个响应都带 X-RateLimit-* 响应头。
有没有不需要 API Key 的免费 PDF API？
匿名使用没有问题：开发者页面写明，调用公开 API 不需要账号，也不需要 Key。OpenAPI 文档把 X-API-KEY 列为认证方式，但下面的调用都没带它。
命令于 2026-10-23 在本机运行的一份服务器上执行，这里把地址换成了 https://pdf123.xyz。输入是两个单页 PDF，由两个很短的 Markdown 文件生成。合并每个文件传一个 fileInput 部分，顺序就是页面在结果里的顺序：
curl -X POST https://pdf123.xyz/api/v1/general/merge-pdfs \
-F [email protected] -F [email protected] \
-o merged.pdf
响应是 HTTP 200，content-type: application/pdf。qpdf --show-npages merged.pdf 输出 2，pdftotext 读到的文字先是 a.pdf 的，再是 b.pdf 的。下载下来的文件按第一个输入命名，也就是 a.pdf，存到原文件旁边之前先改个名。
压缩只传一个文件：
curl -X POST https://pdf123.xyz/api/v1/misc/compress-pdf \
-F [email protected] \
-o small.pdf
这次同样是 HTTP 200。响应头 X-Original-Bytes: 28564 和 X-Compressed-Bytes: 25113 与磁盘上两个文件的大小一致，脚本不用打开文件就能知道这次调用做了什么。这两个数字只属于一个很小的测试文件，不能当作你的文件会被压到多小。
不带 Key，有哪些限制？
服务器在 GET /api/v1/info/status 报告它的大小限制，这个接口同样不需要 Key。它返回的值，换算成 MiB（1 MiB 是 1,048,576 字节）如下：
| 字段 | 值 | 限制的是什么 |
|---|---|---|
maxUploadBytes |
104,857,600（100 MiB） | 一次直接请求的请求体，含 multipart 封装 |
maxChunkedUploadBytes |
524,288,000（500 MiB） | 通过分块上传接口发送的单个文件 |
uploadChunkBytes |
33,554,432（32 MiB） | 每个分块的大小 |
maxOcrPages |
50 | 一次 OCR 请求里需要识别的页数 |
限制页读取的是同一个接口，并补上了网站自己的上限，例如批量处理。请求体超限时返回什么错误，见大 PDF 上传被拒：100 MiB 请求体上限的边界，与那个会误导排查方向的报错。
包括上面这些在内，每个响应都带了三个响应头：x-ratelimit-limit: 100000、x-ratelimit-remaining: 100000 和 x-ratelimit-reset: 0。在我做的这几次调用里，数字没有变化。没有配置周期上限时，服务器写 100000，reset 则一直写 0，所以在那台服务器上，这些响应头宣告的不是一个会递减的配额。它们也无法说明以后某天 pdf123.xyz 的配额是多少：请在你自己的响应上读取，不要把某个数字写死在代码里。响应头的用途见无需登录：匿名限流如何让免费工具继续免费。
接口文档在哪里？
OpenAPI 3 文档在 https://pdf123.xyz/v1/openapi.json，https://pdf123.xyz/swagger-ui 则把同一套 API 放在一个页面里，可以逐个端点试用。每个操作都是 /api/v1 下的 POST，按类别分组：合并是 /general/merge-pdfs，压缩是 /misc/compress-pdf。网站上的工具页调用的是同一批端点。
想要能直接复制运行的例子，示例里常见任务都有 curl、pdfx 和 Node 三种写法。开发者页面还介绍了 SDK、命令行和 MCP。
出错时返回什么？收到 429 该怎么办？
失败的调用返回 application/problem+json，格式由 RFC 9457《Problem Details for HTTP APIs》定义。把一个名为 fake.pdf 的文本文件传两次给合并，返回 HTTP 400 和下面这个响应体（这里重新排了版，键的顺序与返回一致）：
{
"code": "invalid_document",
"detail": "The file is not a valid PDF or it is damaged.",
"error": "The file is not a valid PDF or it is damaged.",
"hint": "Upload a valid, undamaged PDF. Try the Repair tool first.",
"reason": "invalid_pdf",
"status": 400,
"title": "Bad Request",
"type": "https://pdf123.xyz/developers/errors#invalid_document"
}
code 是粗粒度的类别，reason 是具体原因。错误码页列出了两者，并建议先按 reason 分支，再退回到 code。error 重复了 detail，给旧客户端用。
在那台服务器上，我唯一能触发的 429 来自分块上传：已经开着 32 个上传时，再请求开始第 33 个就被拒绝。响应是 HTTP 429，reason 为 upload_limit_reached，code 为 rate_limited，带 retry-after: 60 响应头，同时有常规的 x-ratelimit-* 响应头。32 是服务器的默认值，别的服务器可以设成不同的数。合并、压缩这类操作调用在我的测试里没有返回过 429，但客户端仍然应该处理它：开发者页面把 rate_limited、状态码 429 列为配额用完时的返回。RFC 6585 把这个状态码定义为在给定时间内请求过多，并说明服务器可以带上 Retry-After 告知客户端该暂停多久。
收到 429，客户端该做的事：
- 等够
Retry-After给出的秒数（我看到的响应里是 60），再发同一个请求。不要在紧凑的循环里重试。 - 如果
reason是upload_limit_reached，把留着没用的上传收尾或放弃。DELETE /api/v1/uploads/{id}可以中止一个上传，没完成的上传一小时后自行过期。 - 等待要自己做。SDK、
pdfx命令行和 MCP 服务器不会自动重试。
什么时候值得创建 API Key？
开发者页面给了两个理由：标识你自己的流量，以及调用托管的 MCP 端点 https://pdf123.xyz/mcp，后者一直要求带 Key。在我运行的服务器上，不带 Key 请求 /mcp 返回 401。Key 在那个页面登录后创建，放在 X-API-KEY 请求头里发送。在公开站点上使用 REST API、SDK 和命令行，不需要 Key。自己托管服务器时，可以用环境变量 SECURITY_CUSTOMGLOBALAPIKEY 设一个服务器认可的 Key。
常见问题
PDF123 的 API 真的免费吗？
匿名调用公开 API 不需要账号，也不需要 Key，上面的例子两样都没用。限制就是上面表格里的那些，任何配额以你自己响应上的响应头为准。
调用它一定要登录吗？
不用。只有创建 Key 才需要登录，托管的 MCP 端点要 Key，REST API 不要。
能发送超过 100 MiB 的 PDF 吗？
可以，每个文件最大 500 MiB，走分块上传接口：先创建上传，逐个发送 32 MiB 的分块，完成后把它的 id 传给操作。TypeScript SDK 和 pdfx 会自动切换到这种方式。具体步骤见错误码页的“Files over 100 MB”一节。
怎么知道我调用的服务器有哪些限制？
调用 GET /api/v1/info/status。它报告那台服务器的请求体大小、分块上传的大小和分块大小，以及 OCR 页数上限，限制页的数字就来自它。