Overview 1 分钟阅读

面向开发者的 PaperOffice API：完整指南

规范所在的位置

端点规范是从 API 目录实时生成的。请使用以下文件，而不是从文章中复制端点列表：

  • 面向 AI 客户端的紧凑索引：https://api.paperoffice.ai/latest/docs/llms.txt
  • 完整参考文档：https://api.paperoffice.ai/latest/docs/llms-full.txt
  • OpenAPI 3.1：https://api.paperoffice.ai/latest/docs/openapi.json
  • Agent 技能包：https://api.paperoffice.ai/latest/docs/skill.md
  • Postman 集合：https://api.paperoffice.ai/latest/docs/postman

文档路由是公开的，无需令牌。将 Postman URL 导入 Postman、VS Code 或 Bruno，并在文档版本更新时重新下载。生产环境的基础地址为 https://api.paperoffice.ai/latest；仅开发环境请使用 /dev。

使用 AI 编码助手的快速入门：提供 llms-full.txt 的地址并描述您需要的功能，例如一个发送图像并返回识别文本的函数。

认证与令牌类型

大多数产品端点需要在 Authorization 头中提供 Bearer 令牌。您可以在 PaperOffice 应用下的 账户 → API 中创建令牌。

  • 系统密钥 (po_sk_)：用于具有完全 API 访问权限的服务器到服务器集成。切勿在浏览器中使用。
  • 用户令牌 (po_ut_)：限定单个用户的范围，例如用于 MCP。权限跟随用户及其许可证。
  • 组令牌 (po_gt_)：继承用户组的权限和工作区白名单。
  • 可发布密钥 (po_pk_)：用于浏览器环境。每个请求都需要密钥所有者输入的来源地址，生命周期预算限制消耗量，且禁止删除、账户管理、密钥管理和支付更改。不允许用于 MCP。

没有令牌时，仅可访问基础设施端点（如规范、健康检查和连通性测试）。没有令牌的产品请求将返回 HTTP 403 和代码 TIER_RESTRICTED，而非 HTTP 401。

作业：等待、轮询与结果

处理过程以作业形式运行。作业路径使用带有三个下划线的模式 handler___command，例如用于文本识别的 POST /job/add/paperoffice_aiocr___generate。点符号将被拒绝并返回 JOB_CONFIG_INVALID。

  • 默认情况下，请求会保持连接一段时间。如果作业在规定时间内完成，您将直接获得结果。否则，您将收到带有作业 ID 和轮询地址的 HTTP 202，作业将继续运行。
  • HTTP 202 表示成功而非错误。每 5 到 10 秒轮询一次 GET /job/get/{job_id}，直到状态为 completed（已完成）。结果随后位于 job_result 中。
  • 设置 client_wait=false，您将立即获得作业 ID，并从一开始就进行轮询。
  • 所有响应均为 JSON。客户端应读取稳定的 code 字段，而非本地化的消息文本。

您可以在应用下的 账户 → API → 任务队列 中查看排队中、运行中和已完成的 API 作业。错误代码的完整列表位于规范中；典型情况包括缺少或无效参数（400）、缺少或无效令牌（401）、Credits 不足（402）、禁止的操作（403）以及请求过多（429，请遵守 Retry-After 头）。

启动 SLA：作业何时开始

可选字段 processing_lane 控制作业在队列中的启动时间，而非完成时间。client_wait 控制连接是否等待结果；这两个字段是独立的。

如果不指定 processing_lane，则应用工作区的默认值，否则为尽力而为（best effort）。每个计划均包含免费的尽力而为服务。更快的启动通道是可选的且费用更高。当前的通道及其价格可通过 API 价格列表实时获取；详细信息请参阅 API 文档。

Webhook

Webhook 端点接收作业和账户事件，例如 job.completed、job.failed、job.progress 以及文档、工作区和任务的事件。账户通知（如钱包为空或密钥被撤销）不属于 Webhook 事件。

  • 有效载荷使用 HMAC-SHA256 在 X-Paperoffice-Signature 标头中进行签名。请使用您的 Webhook 密钥对原始请求正文计算签名，如果不匹配，请拒绝该请求。
  • Webhook 通过 API 进行注册、列出、更新、测试和删除。

计费与使用情况

API 调用会从组织的共享池中消耗 Credits，该池与应用共享。某些状态和健康查询不收费；详细信息请参阅 API 文档。因输入无效而被拒绝的调用也会收费；受速率限制的调用则不收费。

您可以在 API 与开发人员 → API 使用情况 下查看带有 Credits 的调用：实时日志显示每次请求，历史记录按日期、处理程序和操作显示使用情况。当 Credits 耗尽时，调用将被拒绝，直到余额充值或自动续充生效。速率限制取决于您的计划；当前限制和响应标头在 API 文档中描述。有关 Credits 的更多信息：PaperOffice AI 中的计费与 Credits。

MCP：连接 AI 助手

MCP 将 AI 助手（如 Claude、ChatGPT、Grok 和 Cursor）直接连接到 PaperOffice。身份验证方式为 OAuth 2.1 或用户/组令牌；系统密钥和可发布密钥在 MCP 中被阻止。生产主机为 https://mcp.paperoffice.ai，配置文件包括 /claude、/chatgpt、/grok、/cursor 和 /dms。设置、权限和数据流：在 Claude、ChatGPT、Grok 和 Cursor 中使用 PaperOffice。

常见问题解答

  • 我在哪里可以找到所有端点？在 llms.txt、llms-full.txt 和 OpenAPI 文件中。它们是实时生成的。
  • 我的服务器应使用哪种令牌？系统密钥，绝不在浏览器中使用。对于浏览器，请使用带有来源和预算的可发布密钥。
  • HTTP 202 是错误吗？不是。作业仍在运行；请轮询结果。
  • 更快的启动通道是否更贵？是的。尽力而为（Best effort）不收取附加费；当前价格请参阅 API 价目表。
  • 被拒绝的调用会收费吗？因输入无效而被拒绝的调用会收费；受速率限制的调用则不收费。