开发文档
REST API
DocUnwrap 解析任务 API —— POST /api/v1/parse 提交、GET /api/v1/tasks/:id 查询。
REST API 是异步任务模型:提交 → 拿 task_id → 轮询状态 → 终态后取结果。
鉴权与错误信封见下;key 的获取见 API Key 管理。
下文以
https://docunwrap.com为例,请替换为你实际访问本站的域名(本地开发即http://localhost:3000)。
提交解析任务
curl -X POST https://docunwrap.com/api/v1/parse \
-H "Authorization: Bearer docunwrap_live_xxxx" \
-H "Content-Type: application/json" \
-d '{
"file_url": "https://example.com/quarterly-report.pdf",
"output_format": "markdown",
"model_preference": "auto"
}'请求字段(snake_case,兼容 camelCase):
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
file_url | string | 是 | 指向 PDF 的 http(s) URL,≤2048 字符。文件须可公开下载 |
file_name | string | 否 | 展示名;缺省从 URL 路径推导 |
output_format | string | 否 | markdown(默认)或 json(结构化块) |
model_preference | string | 否 | auto(默认)/ mineru4 / paddleocr-vl / teleocr / glm-ocr |
成功响应 202:
{ "task_id": "9f1c…", "status": "pending", "output_format": "markdown" }文本层 PDF(数字原生、无需 OCR)通常在数秒内完成;扫描件按页数异步推进。
查询任务
curl https://docunwrap.com/api/v1/tasks/9f1c… \
-H "Authorization: Bearer docunwrap_live_xxxx"响应 200:
| 字段 | 说明 |
|---|---|
task_id / status | 状态机:pending → processing → done | failed(部分页失败仍 done) |
pages_total / pages_processed | 页级进度 |
output_format / error | 请求的格式 / 失败原因(终态才有) |
result_key | 结果的存储键 |
created_at / completed_at | ISO 时间戳 |
任务不存在或不属于当前 key 的属主一律 404 not_found(不泄露存在性)。
读取结果内容:当前推荐经 MCP 的 get_task_result 工具(支持 offset/max_length
分页)或控制台任务详情视图读取全文;result_key 是存储键而非下载 URL。
错误信封
所有错误都是 {"error": {"code": "…", "message": "…"}},限流/余额类附带头部字段:
| HTTP | code | 场景 |
|---|---|---|
| 400 | invalid_json / file_url / output_format / model_pref | 请求体或字段非法 |
| 401 | missing_key / invalid_key | 未带 key / key 不存在、停用或过期 |
| 402 | insufficient_credits | 余额不足一页(附 balance) |
| 403 | banned | 账户被封禁 |
| 404 | not_found | 任务不存在或非属主 |
| 429 | rate_limited / too_many_active_tasks | key 限流(附 retry_after)/ 并发闸(附 retry_after_seconds) |
计费口径与三条接入路径一致(见接入总览): 完成时按实际页数 × 模型单价扣减,创建不预扣。