为 AI Agent 而建，不只为浏览器：API 怎么用

浏览器标签页照样能用：选工具、上传文件、下载结果。Agent 和脚本则不开 UI，直接调用同一批操作。两条路径打到的是一份目录。

每个工具页同时是一个 API 端点

合并、拆分、压缩、OCR、转换：目录里的每个工具都对应 /api/v1/… 上的一个端点。打开工具页往下滚到 Call this from code，里面是一段 curl，参数取自该工具的真实表单，不是通用模板。在公网站匿名调用既不需要账号也不需要 API Key，匿名前缀包括 /api/v1/general/、/api/v1/misc/、/api/v1/security/、/api/v1/convert/ 和 /api/v1/filter/。

合并的示例很具体：

curl -fsS -X POST "$API_BASE/api/v1/general/merge-pdfs" \
  -F "[email protected]" \
  -F "[email protected]" \
  -o merged.pdf

OpenAPI 在 /v1/openapi.json。多步任务用 POST /api/v1/pipeline，传一个有序的 steps 列表。重试不能让变更型任务重复执行时，带上 Idempotency-Key。托管响应会带 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset，遇到 HTTP 429 读 Retry-After（匿名限流）。

同一份目录里的 OCR 由 /api/v1/misc/ocr-pdf 返回 Markdown（text/markdown），不是带隐藏文本层的 PDF。以为这个端点会给出可搜索 PDF 的 Agent，会错误处理下载结果；这里的契约是给流水线用的文本抽取，不是 OCRmyPDF 那样重写 PDF。

会说 MCP 的客户端

MCP（Model Context Protocol）让 Agent 客户端把工具当函数来发现和调用，不用去刮文档。本站在 REST API 旁边、/mcp 上暴露一个 MCP 服务器，兼容客户端连一次就拿到完整目录。

MCP 与 REST 的认证预期一致：工具前缀允许的地方可以匿名；稳定自动化和带门闸的自托管服务器用 API Key。把 Agent 指向 /mcp，和把 curl 指向 /api/v1/… 并不是两套产品。文档见开发者 MCP。

错误结构化，而不是散文

失败返回 application/problem+json（RFC 7807 风格），不是裸 500，也不是一句“出了点问题”。每份载荷都带稳定的错误码（rate_limited、bad_request、invalid_document、missing_dependency 等）、可读的提示，通常还有下一步建议。人扫一眼就懂，Agent 也能据此决定重试、换文件还是停下，不需要有人去读堆栈。

当调用方是脚本时，这种结构比一个友好的 HTML 错误页重要得多。参考开发者错误。

llms.txt 是给工具读的，不是给排名用的

/llms.txt 是全部工具的纯文本索引（名称、一句话简介、URL），由驱动整个站点的同一份目录生成。编码 Agent 和文档工具可以把它当 README 来读。它不是 Google 的排名杠杆：Search 会忽略 /llms.txt（出处：Google 的 AI 优化指南）。因为它由目录生成，不会像手写文件那样悄悄过期。

CLI 与 skill 共用同一套形状

pdfx 既能跑本地 pdf-core，也能用 --cloud 指向一个 base URL。dist/skills/pdf-toolbox/SKILL.md 下的编码 Agent skill 记录了 merge 与 pipeline 的 curl 形状，免得 Agent 自己发明第二套契约。四个客户端，一份目录：同一操作，四种客户端。

浏览器路径没有变化

在标签页里丢文件照旧可用。多出来的表面是同一批端点，供 Agent、脚本或 CI 使用：同样的处理，中间没有人。自托管把这套表面留在你自己的网络里（自托管），托管则仍是匿名试用路径。

API 参考：Swagger。两条路径的基础：帮助 与开发者。