文档解析 API

文档解析采用“上传文件 → 提交异步任务 → 查询状态 → 下载结果”的流程。当前提供本地文本、本地 PowerPoint 和 Cloudflare 文档转换执行器；实际可用工具、价格、格式及限制以 GET /v1/tools 返回为准。消费站点应调用自己的统一附件接口，不应把底层工具 ID 暴露给浏览器用户。

权限与费用

工具服务权限独立于模型权限。API Key 的「允许使用的工具服务」留空时允许调用全部已发布工具；填写逗号分隔的工具 ID 时，只允许调用清单内的工具。工具使用钱包余额，按成功文档计费，不使用订阅额度或分组倍率。

每次提交会预扣目录中的固定费用；成功转为实扣，失败全额退款。上传不会收取解析费用。pricing_display 是可读价格，不需要客户端执行表达式。

Base URL 为 https://api.rokoapi.com/v1，所有请求需要 Authorization: Bearer $API_KEY。文件和结果绑定上传/调用的用户及 Key，同一用户的其他 Key 也不能读取。

可发布工具

下表是当前代码支持的标准配置；某个环境是否已发布、实际价格和更小的管理员限制，仍以该环境的 GET /v1/tools 为准。

text-md-json 不调用外部解析供应商，会保留 Markdown/TXT 原文；CSV、JSON 和代码等内容会放入 Markdown 代码块。文本必须为 UTF-8，可带 UTF-8 BOM；不接受 GBK、二进制数据或包含非法控制字符的文本。

file-md-json 适合含可提取文字层的 PDF、Word、Excel 和 OpenDocument。当前不提供 OCR、页码坐标、边界框或结构化表格保证；扫描件或纯图片 PDF 可能返回无可用文本。本平台固定限制为 10 MiB，并只开放经过服务端签名和结构校验的保守白名单。上游当前格式依据见 Cloudflare 支持格式。

pptx-md-json 在本地安全读取 PPTX ZIP/XML，按幻灯片编号输出 Markdown。它会提取文本框和表格单元格中的文字，但不解释版式、图表、图片、动画或演讲者备注。旧版 .ppt、宏文件 .pptm 不在支持范围。

价格和配置可由管理员调整。客户端应从工具目录读取 pricing_display、max_file_bytes 和 extensions，不要长期硬编码上表数值。

查看工具

curl https://api.rokoapi.com/v1/tools \
  -H "Authorization: Bearer $API_KEY"

从 data[].id 选择工具 ID，检查 extensions、max_file_bytes 和 pricing_display.unit_price（USD/文档）。

上传文件

# 本地文本、Markdown 或代码解析
export TOOL_ID=text-md-json
curl "https://api.rokoapi.com/v1/tools/$TOOL_ID/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]"

# PDF、Word、Excel、OpenDocument 或 CSV 解析
export TOOL_ID=file-md-json
curl "https://api.rokoapi.com/v1/tools/$TOOL_ID/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]"

# PowerPoint 解析
export TOOL_ID=pptx-md-json
curl "https://api.rokoapi.com/v1/tools/$TOOL_ID/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]"

成功返回 HTTP 201。保存响应 id，例如 toolfile_...。一次只能上传一个文件，最大 10 MiB，具体服务可能设置更低上限。文件从上传成功起保留 2 小时。

旧版 .doc、.ppt、扫描件 OCR 和页坐标不在当前能力范围；旧版 .xls 可由 file-md-json 处理。上传的文件 ID 只能用于创建它的工具，不能先通过 text-md-json 上传、再交给其他工具解析。

压缩包展开后的总内容和单次结果均限制为 20 MiB；Office/OpenDocument 最多包含 10,000 个 ZIP 条目。宏文档、加密文档、压缩包及可执行文件均不接受。

提交解析任务

curl "https://api.rokoapi.com/v1/tools/$TOOL_ID/invoke" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: document-request-001" \
  -d '{
    "input": {"file_id": "REPLACE_WITH_UPLOADED_FILE_ID"},
    "options": {"output_formats": ["markdown", "json"]}
  }'

成功返回 HTTP 202，保存 id（tooltask_ 开头）。同一操作重试必须使用相同的幂等键和参数，不会再次预扣；更改文件或输出格式需要新的键，否则返回 409。键长 8–64，只能使用字母、数字、连字符和下划线。不要在每次网络重试时生成新键。

省略 options 默认生成两种格式。初版不接受 URL、OCR 开关、客户端价格或其他选项。

查询与获取结果

curl "https://api.rokoapi.com/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

status 为 queued、running、succeeded 或 failed。建议每 2–5 秒查询一次；服务接受任务后最多处理 300 秒，超时后失败退款。不要因暂时未完成而重新创建任务。

成功后获取结果：

curl "https://api.rokoapi.com/v1/tasks/$TASK_ID/result?format=markdown" \
  -H "Authorization: Bearer $API_KEY" \
  -o result.md

curl "https://api.rokoapi.com/v1/tasks/$TASK_ID/result?format=json" \
  -H "Authorization: Bearer $API_KEY" \
  -o result.json

JSON 包含 schema_version、markdown、structure_source、capabilities、warnings、input_bytes，并非页级版面结构。请处理警告，不要把非空输出视为文档已完整识别。

结果从任务提交起保留 2 小时，以 expires_at 为准。过期读取返回 410，任务状态及账务记录仍可查询。额度耗尽的 Key 仍可读取已付费结果，但过期、停用或撤销工具授权的 Key 不可读取。

文件清理与账务

• GET /v1/tool-files/{file_id}：文件元数据。
• DELETE /v1/tool-files/{file_id}：请求后台删除；有未完成任务时返回 429，稍后重试。
• GET /v1/tool-tasks：当前 Key 最近 100 个任务和预扣/实扣记录。额度字段是账户 quota 单位，不是美元。

工具明细目前在工具任务记录中查看，不出现在模型消费日志中。每个用户最多保留 20 个待清理文件、同时运行或排队 4 个任务；超出返回 429。

常见错误

任务失败不会自动改用更贵的解析器。对于扫描件和复杂版面，应等待相应 OCR 服务上线。

文件使用项目公开存储桶，知晓对象地址的人可在删除前访问。过期后后台每分钟清理；服务故障期间删除可能延迟，恢复后重试。