DocUnwrap 文档
开发文档

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_urlstring是指向 PDF 的 http(s) URL,≤2048 字符。文件须可公开下载
file_namestring否展示名;缺省从 URL 路径推导
output_formatstring否markdown(默认)或 json(结构化块)
model_preferencestring否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_atISO 时间戳

任务不存在或不属于当前 key 的属主一律 404 not_found(不泄露存在性)。

读取结果内容:当前推荐经 MCP 的 get_task_result 工具(支持 offset/max_length 分页)或控制台任务详情视图读取全文;result_key 是存储键而非下载 URL。

错误信封

所有错误都是 {"error": {"code": "…", "message": "…"}},限流/余额类附带头部字段:

HTTPcode场景
400invalid_json / file_url / output_format / model_pref请求体或字段非法
401missing_key / invalid_key未带 key / key 不存在、停用或过期
402insufficient_credits余额不足一页(附 balance)
403banned账户被封禁
404not_found任务不存在或非属主
429rate_limited / too_many_active_taskskey 限流(附 retry_after)/ 并发闸(附 retry_after_seconds)

计费口径与三条接入路径一致(见接入总览): 完成时按实际页数 × 模型单价扣减,创建不预扣。

On this page