文档解析 API

接入概览

所有示例中的 GATEWAY_BASE_URL 均指你的网关域名，不是 mineru.net。文档页面只展示示例，不发起解析请求。

先获取管理员分配的 Gateway Key，再提交文档 URL 或申请文件上传链接。保存返回的 Gateway ID，轮询至 done 后读取 full_zip_url。

地址与鉴权

业务请求使用 Authorization: Bearer <Gateway Key>。上游 MinerU Token 由网关管理；管理控制台的登录会话不能替代 Gateway Key。

Authorization: Bearer <Gateway Key>
Content-Type: application/json
Idempotency-Key: <unique-operation-id>

任务与批次按 Key 所有者隔离，查询需要同一所有者的有效 Key。PDF 上传扩展则必须使用创建批次的原始 Key。

运行示例前设置环境变量。ID、上传链接取自前一步响应；幂等值由调用方生成，同一次创建重试时保持不变。

创建单文件任务

通过文档 URL 创建解析任务。此接口接收 JSON，不接收文件二进制。code=0 只表示创建成功，解析结果需后续查询。

请求参数

curl --request POST "$GATEWAY_BASE_URL/api/v4/extract/task" \
  --header "Authorization: Bearer $GATEWAY_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data @- <<JSON
{
  "url": "$DOCUMENT_URL",
  "model_version": "pipeline",
  "page_ranges": "1",
  "enable_formula": true,
  "enable_table": true
}
JSON

响应示例

{
  "code": 0,
  "msg": "ok",
  "trace_id": "gw_example",
  "data": {
    "task_id": "11111111-1111-4111-8111-111111111111"
  }
}

示例值仅用于说明；实际 ID 和链接请读取接口响应。

查询单文件任务

使用创建响应中的 task_id 查询。网关始终查询任务绑定的渠道。只有 state=done 时才应使用 full_zip_url 获取结果。

请求参数

curl --request GET "$GATEWAY_BASE_URL/api/v4/extract/task/$TASK_ID" \
  --header "Authorization: Bearer $GATEWAY_API_KEY"

响应示例

{
  "code": 0,
  "msg": "ok",
  "trace_id": "gw_example",
  "data": {
    "task_id": "11111111-1111-4111-8111-111111111111",
    "state": "done",
    "full_zip_url": "https://results.example/result.zip",
    "err_msg": ""
  }
}

示例值仅用于说明；实际 ID 和链接请读取接口响应。

申请本地文件上传

传入文件列表，返回一个 batch_id 与按请求顺序对应的 file_urls。即使只上传一个本地文件，也使用此接口。

请求参数

curl --request POST "$GATEWAY_BASE_URL/api/v4/file-urls/batch" \
  --header "Authorization: Bearer $GATEWAY_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data @- <<JSON
{
  "files": [
    {
      "name": "document.pdf",
      "data_id": "document-001",
      "page_ranges": "1"
    }
  ],
  "model_version": "pipeline"
}
JSON

响应示例

{
  "code": 0,
  "msg": "ok",
  "trace_id": "gw_example",
  "data": {
    "batch_id": "22222222-2222-4222-8222-222222222222",
    "file_urls": [
      "https://storage.example/upload-placeholder"
    ]
  }
}

示例值仅用于说明；实际 ID 和链接请读取接口响应。

curl --request PUT --upload-file ./document.pdf "$UPLOAD_URL"

创建 URL 批量任务

一次提交 1–50 个可访问的文档 URL。每个文件建议提供唯一 data_id，便于关联解析结果和页数结算；不要假定结果顺序与请求顺序相同。

请求参数

curl --request POST "$GATEWAY_BASE_URL/api/v4/extract/task/batch" \
  --header "Authorization: Bearer $GATEWAY_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data @- <<JSON
{
  "files": [
    {
      "url": "$DOCUMENT_URL",
      "data_id": "document-001",
      "page_ranges": "1"
    }
  ],
  "model_version": "pipeline"
}
JSON

响应示例

{
  "code": 0,
  "msg": "ok",
  "trace_id": "gw_example",
  "data": {
    "batch_id": "22222222-2222-4222-8222-222222222222"
  }
}

示例值仅用于说明；实际 ID 和链接请读取接口响应。

查询批量结果

适用于上传批次和 URL 批次。extract_result 逐文件返回状态和结果，整个批次可能同时包含成功、处理中和失败的文件。

请求参数

curl --request GET "$GATEWAY_BASE_URL/api/v4/extract-results/batch/$BATCH_ID" \
  --header "Authorization: Bearer $GATEWAY_API_KEY"

响应示例

{
  "code": 0,
  "msg": "ok",
  "trace_id": "gw_example",
  "data": {
    "batch_id": "22222222-2222-4222-8222-222222222222",
    "extract_result": [
      {
        "file_name": "document.pdf",
        "data_id": "document-001",
        "state": "done",
        "full_zip_url": "https://results.example/result.zip",
        "err_msg": ""
      }
    ]
  }
}

示例值仅用于说明；实际 ID 和链接请读取接口响应。

通过网关上传 PDF

为浏览器无法直接访问存储上传链接的情况提供同源上传。先申请本地文件上传批次，再将 PDF 原始字节 PUT 到此接口。

请求参数

curl --request PUT "$GATEWAY_BASE_URL/gateway/v1/batches/$BATCH_ID/files/0" \
  --header "Authorization: Bearer $GATEWAY_API_KEY" \
  --header 'Content-Type: application/pdf' \
  --upload-file ./document.pdf

响应示例

{
  "code": 0,
  "msg": "ok",
  "trace_id": "gw_example",
  "data": {
    "batch_id": "22222222-2222-4222-8222-222222222222",
    "uploaded_bytes": 1024
  }
}

示例值仅用于说明；实际 ID 和链接请读取接口响应。

解析参数

下面为单任务与批量解析选项。批量请求中，is_ocr、data_id、page_ranges 属于 files[]；其余共享选项放在顶层。no_cache 和 cache_tolerance 仅在本文的单 URL 任务中使用。

响应与任务状态

响应使用 code / msg / trace_id / data。code 可以是数字或上游字符串；同时检查 HTTP 状态与 code。code=0 不等于文档已完成。JSON trace_id 与 X-Gateway-Trace-Id 一致，可用于定位请求。

响应字段

非 HTML 结果通常包含 full.md、内容列表 JSON、布局与模型结果，以及图片和所选额外格式；HTML 结果包含 full.md 和 main.html。具体文件随模型与上游输出变化。

幂等与重试

三个 POST 创建接口都接受可选的 Idempotency-Key，建议始终设置。作用域为 Gateway Key + 路由。相同值与相同请求返回原任务；变更请求内容却复用该值将返回 HTTP 409 / -70005。

单任务幂等记录保留 24 小时，批量保留 7 天。上传链接仅有效 24 小时，过期回放返回 HTTP 410 / -70012。创建超时后使用原 Key 与原请求；submission_unknown 只查询，不新建。

{
  "code": -70008,
  "msg": "upstream submission status is unknown",
  "trace_id": "gw_example",
  "data": {
    "task_id": "11111111-1111-4111-8111-111111111111",
    "state": "submission_unknown"
  }
}

限制与页数额度

精准解析按官方详细接口约束：每文件不超过 200 MB / 200 页，每批最多 50 个文件。文档格式支持取决于上游模型；网关 PDF 上传扩展仅接受 PDF。

官方列出的源格式包括 PDF、Word、PowerPoint、Excel、图片与 HTML；HTML 选择 MinerU-HTML，其他格式使用 pipeline 或 vlm。控制台文件测试目前仅支持 PDF。

启用额度的账户按 pages-v1 管理：1 页 = 1 额度。创建时同时冻结账户与 Key 可用额度，每文件默认预占 200 页；page_ranges 可缩小范围，批量累加。额度不足返回 HTTP 402 / -70012，整个提交回滚，不调用上游。

成功文件按确认的页数结算并释放差额；失败文件释放冻结。缺少页数或提交结果不明时保留冻结等待核账。查询不重复扣费。网关额度不是人民币定价，也不等于上游每日优先页数。

终态任务默认保留 90 天（可由管理员调整），结果下载链接的有效期由上游决定。任务仍可查询不代表下载链接永远有效。

错误码与处理

先看 HTTP 状态，再看 code 与 msg。同一错误码可能有不同 HTTP 语义；例如 -70012 在 402 表示额度不足，在 410 表示上传链接过期。

上游常见错误

合法的 MinerU 错误包尽量保留原 code / msg。遇到上游凭据或亲和问题，请提供 Gateway Trace ID 联系管理员，不向应用暴露上游 Token。

健康检查

这两个接口不要求 Gateway Key，但部署网络策略可能限制访问。响应为简单 status 对象，不使用 code/msg/data 包络。live 返回 HTTP 200 / ok；ready 在依赖就绪时返回 200 / ok，否则 503 / not_ready。

curl "$GATEWAY_BASE_URL/gateway/v1/health/live"
curl "$GATEWAY_BASE_URL/gateway/v1/health/ready"

{ "status": "ok" }

管理接口 /admin/v1 使用独立的会话鉴权，不属于本文的 Gateway Key 接口。