Skip to content

Transforms complex documents like PDFs and Office docs into LLM-ready markdown/JSON for your Agentic workflows.

docs(api): specify Tasks, Files and file_parse response contracts

myhlolifb3f81df0a5b
diff --git a/docs/next/api/README.md b/docs/next/api/README.md
index 4fcce138..11281972 100644
--- a/docs/next/api/README.md
+++ b/docs/next/api/README.md
@@ -59,6 +59,9 @@ ID 使用 OpenAI 风格的前缀加随机串。官方 API 使用 24 字符 base6
JSON、逐文件上传、独立结果链接与 Router 负载规则见 [V1 tasks](tasks.md)。SaaS 可以独立实现同一契约,并返回 OSS 直链;客户端不要求其实现本地 Files 下载路由。
+各接口的成功状态码、Content-Type 和返回对象见 [响应总览](responses.md#成功响应)。
+创建、查询、取消及本地上传均返回完整的 [TaskStatusResponse](tasks.md#taskstatusresponse);列表返回分页摘要,Files 下载返回二进制附件。
+
需要单文件直传和同步附件响应时,可另外启动 [file_parse 包装服务](file-parse.md),它提供自己的 `/v1/file_parse`、查询和下载接口,并通过上面的 Tasks 协议连接任意部署。
## 认证
@@ -79,7 +82,7 @@ Local Parse Server 默认监听 loopback 且不启用鉴权。启用 `--api-key`
- 错误响应使用 OpenAI-compatible envelope,详见 [响应与错误](responses.md)。
- 资源级接口及 `POST /v1/tasks` 使用 JSON,上传字节使用返回链接要求的内容类型。
- 时间字段按 endpoint 语义选择 ISO-8601 UTC 字符串或 Unix 秒级时间戳。
-- 成功和失败响应都应携带 `X-Request-Id`。
+- 请求追踪属于部署扩展;当前 Python API Server 和 Router 不统一提供 `X-Request-Id`,详见 [请求追踪](responses.md#请求追踪)。
- `Idempotency-Key` 支持属于部署能力;当前自部署 tasks 不提供创建请求幂等重试保证,恢复操作应使用原 `task_id`。
- 未知响应字段必须被客户端忽略,以支持服务端向后兼容扩展。
- 请求中的可选字段可以省略;省略时按该字段默认值处理。
diff --git a/docs/next/api/file-parse.md b/docs/next/api/file-parse.md
index 1b01ea5a..3898c40b 100644
--- a/docs/next/api/file-parse.md
+++ b/docs/next/api/file-parse.md
@@ -44,58 +44,261 @@ MINERU_API_URL=https://mineru.net/api MINERU_API_KEY=your-key \
curl --max-time 7200 -D response.headers -o response.body \
http://127.0.0.1:8003/v1/file_parse \
- -F 'request_id=report-20261022-001' \
+ -F 'request_id=report-20261023-001' \
-F 'tier=flash' -F 'ocr_mode=txt' \
-F 'output_formats=default' -F 'output_formats=docx'
```
`output_formats` 的列表语义与 [Tasks](tasks.md) 一致;multipart 中不使用 JSON 字符串或逗号分隔字符串。
-| 选择 | HTTP 成功附件 |
-|---|---|
-| 单选 `default` | ZIP,包含 Markdown、中间协议、Structured Content、外置图片。 |
-| 单选 `docx` | 图片内嵌的 DOCX。 |
-| 单选 `html` | 图片内嵌的 HTML。 |
-| 单选 `latex` | ZIP,包含 TeX 和外置图片。 |
-| 多个不同格式 | 上游生成的单个 ZIP。 |
+## 响应结构与格式
-成功返回 `200`、正确的 Content-Type 和 `Content-Disposition: attachment`,文件名为 `<输入文件主名>.<扩展名>`,并携带 `X-Request-ID`、`X-Task-ID`。包装服务原样返回验证过的上游产物,不重新渲染或打包。
+以下三个接口均属于独立 file_parse 包装服务。它们的 JSON 状态对象是下文的 `StatusResponse`,不是 Tasks 的 `TaskStatusResponse`。
-每次调用在确认上游文件就绪后开始计时,等待包含排队、解析与导出。接收文件、上游上传和结果下载不占此预算,独立使用传输空闲超时。缓存命中跳过上传。
+| 接口 | HTTP | Content-Type | 正文格式 |
+|---|---|---|---|
+| `POST /v1/file_parse`,同步等待成功 | 200 | 随输出格式 | ZIP、DOCX 或 HTML 附件字节。 |
+| `POST /v1/file_parse`,等待到期或 `wait_timeout=0` | 202 | `application/json` | 完整 `StatusResponse`,保存 `status_url` 后继续查询。 |
+| `GET /v1/file_parse/{request_id}`,查询成功 | 200 | `application/json` | 完整 `StatusResponse`,即使已知任务状态为失败、取消或提交结果未知。 |
+| `GET /v1/file_parse/{request_id}/result`,下载成功 | 200 | 随输出格式 | 与同步成功时相同的附件字节。 |
+| 上述接口的已知业务、存储或上游调用错误 | 4xx / 5xx | `application/json` | 包装服务错误对象;已有恢复记录时同时携带状态字段。 |
-- 正常轮询间隔为 2 秒。
-- 连接、元数据请求、传输空闲超时分别为 10、30、600 秒。
-- `wait_timeout=0` 在文件就绪后直接返回 `202` 查询信息;即使已经完成也不下载附件。
-- 等待到期返回 `202` JSON 和 `Location: <status_url>`,上游继续执行。
-- HTTP 客户端和反向代理的读取超时应覆盖上传、同步等待和结果传输;例如客户端配置 7200 秒,代理按业务文件大小配置相应超时。
+JSON 正文使用 UTF-8;可空字段输出 `null`,不以省略字段代替。下列示例的 ID、地址为示意值。
+
+### POST /v1/file_parse:200 附件响应
+
+成功时直接返回文件内容,不包含 JSON 外层包装,也不把文件编码为 Base64。
+文件名为 `<输入文件主名>.<产物扩展名>`,例如输入 `report.pdf`:
+
+| `output_formats` | 下载文件名 | Content-Type | 文件内容 |
+|---|---|---|---|
+| `["default"]` | `report.zip` | `application/zip` | `markdown.md`、`middle_json.json`、`structured_content.json`、`images/`;显式启用后附加可用 `model_output.json`。 |
+| `["docx"]` | `report.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | 图片内嵌的 DOCX。 |
+| `["html"]` | `report.html` | `text/html; charset=utf-8` | 图片内嵌的 UTF-8 HTML。 |
+| `["latex"]` | `report.zip` | `application/zip` | `document.tex`、`images/`。 |
+| 多个不同格式 | `report.zip` | `application/zip` | 各格式平铺在一个 ZIP 中,不嵌套 ZIP;DOCX/HTML 成员为 `document.docx`、`document.html`。 |
+
+包装服务原样返回验证过的上游产物,不重新渲染或打包。完整成员规则、图片及公式行为沿用 [Tasks 输出格式](tasks.md#输出格式与下载)。
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/zip
+Content-Disposition: attachment; filename="report.zip"
+X-Request-ID: report-20261023-001
+X-Task-ID: job_0123456789abcdef01234567
+
+<ZIP 文件二进制内容>
+```
+
+| 响应头 | 类型 | 返回条件及含义 |
+|---|---|---|
+| `Content-Type` | string | 成功附件的 MIME 类型,按上表确定。 |
+| `Content-Disposition` | string | `attachment` 及建议文件名;非 ASCII 文件名可能使用标准的 `filename*` 编码。 |
+| `X-Request-ID` | string | 成功附件必带,值为包装服务的请求 ID。 |
+| `X-Task-ID` | string | 成功附件必带,值为已确认的上游 Tasks ID。 |
+
+### StatusResponse:查询与 202 的完整 JSON 对象
+
+以下七个顶层字段均会出现。状态对象不返回 Tasks 的 `files/uploads/progress`,不暴露上游上传链接或签名下载地址。
+
+| 字段 | JSON 类型 | 可为 null | 含义 |
+|---|---|---|---|
+| `request_id` | string | 否 | 包装服务的恢复标识,来自请求或自动生成。 |
+| `task_id` | string | 是 | 已确认的上游父任务 ID;尚未获得有效创建响应时为 `null`。 |
+| `status` | string | 否 | 包装服务保存的单文件状态,具体取值见下表。 |
+| `status_url` | string | 否 | 包装服务自身的完整状态查询 URL。 |
+| `result_url` | string | 是 | `completed` 时指向包装服务自身的 `/v1/file_parse/{request_id}/result`,其他状态为 `null`。 |
+| `output_formats` | array of string | 否 | 按首次出现去重后的输出格式。 |
+| `error` | object | 是 | 保存的最近错误或上游逐文件错误;无错误时为 `null`,具体字段见“错误响应”。 |
+
+| `status` | 含义 |
+|---|---|
+| `prepared` | 本地源文件和恢复记录已持久化,尚未开始提交。 |
+| `submitting` | 正在向上游创建任务,尚无确认后的 `task_id`。 |
+| `waiting_upload` | 上游源文件尚未确认就绪。 |
+| `queued` | 已进入上游执行队列。 |
+| `running` | 上游正在解析或导出。 |
+| `completed` | 上游完整产物已生成,可通过包装服务下载。 |
+| `failed` | 已知失败,读取 `error`。 |
+| `canceled` | 上游单文件任务已被取消。 |
+| `submission_unknown` | 创建请求可能已被上游接受,但包装服务没有获得有效任务 ID,不自动重放创建请求。 |
+
+包装服务仅处理一个输入,不使用父 Tasks 的 `partial` 聚合状态。`completed` 表示上游产物已就绪;实际下载仍可能因结果过期或传输失败返回错误。
+
+### POST /v1/file_parse:202 JSON 响应
+
+等待预算耗尽时,返回 `202 Accepted` 和完整 `StatusResponse`。这表示上游继续执行,不是解析失败。
+`wait_timeout=0` 在源文件确认就绪后直接返回 `202`;即使任务已经完成,也返回 JSON,此时 `status` 可以是 `completed`,`result_url` 已非空。
+
+```http
+HTTP/1.1 202 Accepted
+Content-Type: application/json
+Location: http://127.0.0.1:8003/v1/file_parse/report-20261023-001
+Retry-After: 2
+X-Request-ID: report-20261023-001
+X-Task-ID: job_0123456789abcdef01234567
+```
+
+| 响应头 | 返回条件及含义 |
+|---|---|
+| `Location` | 202 必带,与正文 `status_url` 相同。 |
+| `Retry-After` | 202 必带,当前值为字符串 `2`,单位为秒,提示查询间隔。 |
+| `X-Request-ID` | 202 必带,与正文 `request_id` 相同。 |
+| `X-Task-ID` | 已确认上游任务 ID 时携带,与正文 `task_id` 相同。 |
-## 超时与断连后查询
+完整 JSON 正文示例:
```json
{
- "request_id": "report-20261022-001",
- "task_id": "task_example",
+ "request_id": "report-20261023-001",
+ "task_id": "job_0123456789abcdef01234567",
"status": "running",
- "status_url": "http://127.0.0.1:8003/v1/file_parse/report-20261022-001",
+ "status_url": "http://127.0.0.1:8003/v1/file_parse/report-20261023-001",
"result_url": null,
- "output_formats": ["default", "docx"],
+ "output_formats": [
+ "default"
+ ],
"error": null
}
```
-`GET /v1/file_parse/{request_id}` 查询状态,完成后 `result_url` 指向包装服务自己的 `/v1/file_parse/{request_id}/result`。调用者不需要上游密钥。
+### GET /v1/file_parse/{request_id}:200 状态查询
-```bash
-curl http://127.0.0.1:8003/v1/file_parse/report-20261022-001
-curl --fail-with-body -o report.zip \
- http://127.0.0.1:8003/v1/file_parse/report-20261022-001/result
+查询已有记录且上游状态刷新成功时,返回 `200 OK`、`Content-Type: application/json` 和完整 `StatusResponse`。
+返回值可以是 `running`,也可以是 `completed/failed/canceled/submission_unknown`;HTTP `200` 不表示解析成功。
+当前状态查询不统一附加 `X-Request-ID/X-Task-ID`,从 JSON 字段读取这两个标识。
+
+```json
+{
+ "request_id": "report-20261023-001",
+ "task_id": "job_0123456789abcdef01234567",
+ "status": "completed",
+ "status_url": "http://127.0.0.1:8003/v1/file_parse/report-20261023-001",
+ "result_url": "http://127.0.0.1:8003/v1/file_parse/report-20261023-001/result",
+ "output_formats": [
+ "default"
+ ],
+ "error": null
+}
+```
+
+若刷新上游时本次调用失败,则返回非 2xx 错误 JSON;原任务仍可能存在并继续执行,使用相同 `request_id` 继续查询。
+
+### GET /v1/file_parse/{request_id}/result:200 附件下载
+
+成功响应的二进制格式、MIME、命名及 `X-Request-ID/X-Task-ID` 与同步 POST 的 200 附件相同。
+调用者不需要上游 API Key。每次下载先查询原任务并获取当前下载链接;结果未就绪返回 `409 result_not_ready`,没有已确认上游任务时也可能返回 `409 task_not_created`。
+下载中断可以再次 GET。签名失效时重新查询原任务,最多尝试 3 次;上游结果已过期且无法恢复时返回错误,不自动重新解析。
+
+## 错误响应
+
+file_parse 使用自己的错误结构,不能按主 Tasks 接口的 `ErrorDetail` 要求 `type/param` 必带。
+包装层直接返回的 `error` 包含以下三个字段,JSON 值中的 `upstream_status` 不省略:
+
+| 字段 | JSON 类型 | 可为 null | 含义 |
+|---|---|---|---|
+| `error.code` | string | 否 | 包装层错误码或保留的上游错误码。 |
+| `error.message` | string | 否 | 错误说明。 |
+| `error.upstream_status` | integer | 是 | 已知上游 HTTP 错误状态码;本地错误、网络异常或通过任务状态得知的解析失败可以为 `null`。 |
+
+### 没有恢复记录时
+
+只返回顶层 `error`,没有 `request_id/task_id/status_url` 等状态字段。例如提交 JSON 而不是 multipart:
+
+```http
+HTTP/1.1 415 Unsupported Media Type
+Content-Type: application/json
```
-结果未就绪时下载接口返回 `409 result_not_ready`。下载中断可以再次 GET;每次会查询最新下载链接。签名失效时重新查询原任务,最多尝试 3 次;上传失败同样先查询状态,确认已上传成功便不重传。
+```json
+{
+ "error": {
+ "code": "unsupported_media_type",
+ "message": "Expected multipart/form-data",
+ "upstream_status": null
+ }
+}
+```
+
+### 已有恢复记录时
+
+返回完整 `StatusResponse` 的七个顶层字段,但用本次操作的错误覆盖正文 `error`。`status` 仍表示该记录当前状态,不会因为本次 HTTP 失败就统一改成 `failed`。
+例如查询尚未完成的结果,HTTP 为 `409 Conflict`,任务仍为 `running`:
+
+```json
+{
+ "request_id": "report-20261023-001",
+ "task_id": "job_0123456789abcdef01234567",
+ "status": "running",
+ "status_url": "http://127.0.0.1:8003/v1/file_parse/report-20261023-001",
+ "result_url": null,
+ "output_formats": [
+ "default"
+ ],
+ "error": {
+ "code": "result_not_ready",
+ "message": "The result is not ready",
+ "upstream_status": null
+ }
+}
+```
+
+当前错误响应不保证附加 `X-Request-ID/X-Task-ID` 或 `Location`,恢复信息从 JSON 正文读取。只取得了客户端预先指定的 ID、但没有对应恢复记录时,仍使用前一种仅含 `error` 的结构。
-状态包括接收完成后的 `prepared/submitting`,以及单文件 Tasks 的 `waiting_upload/queued/running/completed/failed/canceled`。`submission_unknown` 表示创建请求可能已被上游接受,但包装服务没有获得有效任务 ID:不会自动重放创建请求,不能承诺找回这个不确定窗口内的任务。
+状态查询成功响应中的 `error` 是持久化的错误快照:它可能是上述三字段结构并额外含 `http_status`,也可能保留上游逐文件错误的 `type/code/message/param` 或其他字段。
+其中 `http_status` 是包装层保存的错误响应状态,不是 `upstream_status`;客户端应容忍错误对象的扩展字段。
+例如创建结果未知后,状态查询仍可返回 `200 OK` 和以下完整状态,不自动再次创建任务:
+
+```json
+{
+ "request_id": "report-20261023-001",
+ "task_id": null,
+ "status": "submission_unknown",
+ "status_url": "http://127.0.0.1:8003/v1/file_parse/report-20261023-001",
+ "result_url": null,
+ "output_formats": [
+ "default"
+ ],
+ "error": {
+ "code": "submission_unknown",
+ "message": "Task creation outcome is unknown; not resubmitting",
+ "upstream_status": null,
+ "http_status": 502
+ }
+}
+```
+
+### 常见错误状态码
+
+| HTTP | 常见 code | 含义 |
+|---|---|---|
+| 400 | `invalid_request`、`upload_interrupted` | 参数、多文件、空文件等校验失败,或完整接受前上传中断。 |
+| 404 | `request_not_found` | 包装服务中没有记录,或恢复记录已过保留期。 |
+| 408 | `upload_receive_timeout` | 接收入站请求体时发生传输空闲超时。 |
+| 409 | `request_id_conflict`、`result_not_ready`、`task_not_created` 或取消错误码 | ID 对应不同请求、结果未就绪、尚无确认任务或上游已取消。 |
+| 410 | `upload_expired` | 包装层确认上游上传窗口已经过期。 |
+| 415 | `unsupported_media_type` | POST 不是 `multipart/form-data`。 |
+| 500 | `storage_error` | 包装服务保存源文件、结果或访问本地存储失败。 |
+| 502 | `submission_unknown`、`upstream_unreachable`、`upstream_protocol_error`、`invalid_result`、下载错误码或上游错误码 | 上游创建、查询、传输或解析失败,或结果校验失败。 |
+
+上游认证失败以包装层的 `502` 返回,例如 `error.code="invalid_api_key"`、`error.upstream_status=401`;包装入口本身没有 API Key 认证,不把上游配置错误伪报为入口鉴权失败。
+`submission_unknown` 首次创建失败通常返回 `502`;后续请求仍可能得到 `409/502`,应查询原恢复记录,不自动重放创建。
+
+## 等待、超时与断连后查询
+
+每次调用在确认上游文件就绪后开始计时,等待包含排队、解析与导出。接收文件、上游上传和结果下载不占此预算,独立使用传输空闲超时。缓存命中跳过上传。
+
+- 正常轮询间隔为 2 秒。
+- 连接、元数据请求、传输空闲超时分别为 10、30、600 秒。
+- HTTP 客户端和反向代理的读取超时应覆盖上传、同步等待和结果传输;例如客户端配置 7200 秒,代理按业务文件大小配置相应超时。
+
+```bash
+curl http://127.0.0.1:8003/v1/file_parse/report-20261023-001
+curl --fail-with-body -o report.zip \
+ http://127.0.0.1:8003/v1/file_parse/report-20261023-001/result
+```
-错误响应使用 `error.code/message/upstream_status`。已接受请求的错误还包含请求 ID 和查询地址。参数错误返回 `400`,内容类型错误返回 `415`,ID 冲突或结果未就绪返回 `409`,记录不存在或已过保留期返回 `404`;上游调用或解析失败通常返回 `502` 并保留上游错误码。等待预算耗尽返回 `202`,不是解析失败。
+完整接收后的客户端断连不取消已托管的上传或解析。上传失败先查询状态,确认已经就绪便不重传;若保留的源文件仍可用,使用相同请求 ID 和相同输入可继续原任务。
## 去重与持久化边界
@@ -113,10 +316,10 @@ curl --fail-with-body -o report.zip \
```bash
python scripts/http_file_parse_example.py report.pdf --output results/report.docx \
- --output-format docx --request-id report-20261022-002
+ --output-format docx --request-id report-20261023-002
python scripts/http_file_parse_example.py report.pdf --wait-timeout 0 \
- --request-id report-20261022-003
+ --request-id report-20261023-003
```
后续查询和下载仍使用上面的包装接口,不需要安装 MinerU SDK 或重建 `ParseResult`。
diff --git a/docs/next/api/files.md b/docs/next/api/files.md
index 560c22ca..05927abb 100644
--- a/docs/next/api/files.md
+++ b/docs/next/api/files.md
@@ -9,9 +9,119 @@ Files 保存源文件视图与已生成的结果。异步解析统一使用 [Tas
| GET | `/v1/files/{file_id}/content` | 流式下载已保存的解析产物;源文件不提供公共下载。 |
| DELETE | `/v1/files/{file_id}` | 删除文件视图;正在执行和下载的引用继续受保护。 |
-元数据包括 `id/object/file_name/bytes/created_at/expires_at/purpose/sha256sum`。
-`purpose` 为 `parse`(源文件)或 `parse_output`(结果);删除返回 `id/object/deleted`。
-列表使用 `object: list`、`data`、`first_id`、`last_id`、`has_more`;默认 20 条,上限 100。
+## FileObject:文件元数据
+
+元数据接口成功返回 `200 OK`,`Content-Type: application/json`,JSON 正文使用 UTF-8。
+下列字段在当前本地 API Server 和 Router 的文件对象中均会出现;可空值写为 `null`,不省略字段。
+
+| 字段 | JSON 类型 | 可为 null | 含义 |
+|---|---|---|---|
+| `id` | string | 否 | 不透明的 Files ID;Router 返回自己的公共 ID。 |
+| `object` | string | 否 | 固定为 `file`。 |
+| `file_name` | string | 否 | 文件逻辑名称;结果采用 `<输入文件主名>.<产物扩展名>`。 |
+| `bytes` | integer | 否 | 实际保存的文件大小,单位为字节。 |
+| `created_at` | integer | 否 | 文件视图创建时间,Unix 秒级时间戳。 |
+| `expires_at` | integer | 是 | 文件视图的过期时间,Unix 秒;活动引用或保留策略可能使其暂为 `null`。 |
+| `purpose` | string | 否 | `parse` 表示源文件,`parse_output` 表示结果。 |
+| `sha256sum` | string | 是 | 保存字节的小写 SHA-256;未提供元数据时为 `null`。 |
+
+Files 的时间字段为 Unix 秒级整数,与 Tasks 的 ISO-8601 时间字符串不同。
+
+## GET /v1/files/{file_id}:查询元数据
+
+成功返回 **`200 OK` + `application/json`**,正文直接是 `FileObject`,没有额外包装:
+
+```json
+{
+ "id": "file-result0123456789abcdef",
+ "object": "file",
+ "bytes": 4096,
+ "created_at": 1792728001,
+ "expires_at": null,
+ "file_name": "report.zip",
+ "purpose": "parse_output",
+ "sha256sum": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+}
+```
+
+示例中的 ID、大小、时间和 hash 为示意值。源文件元数据使用相同结构,`purpose` 为 `parse`,`file_name` 为输入文件名。
+
+## GET /v1/files:列出文件
+
+成功返回 **`200 OK` + `application/json`**,每个 `data` 元素都是完整的 `FileObject`:
+
+```json
+{
+ "object": "list",
+ "data": [
+ {
+ "id": "file-result0123456789abcdef",
+ "object": "file",
+ "bytes": 4096,
+ "created_at": 1792728001,
+ "expires_at": null,
+ "file_name": "report.zip",
+ "purpose": "parse_output",
+ "sha256sum": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+ }
+ ],
+ "first_id": "file-result0123456789abcdef",
+ "last_id": "file-result0123456789abcdef",
+ "has_more": false
+}
+```
+
+| 字段 | JSON 类型 | 可为 null | 含义 |
+|---|---|---|---|
+| `object` | string | 否 | 固定为 `list`。 |
+| `data` | array of object | 否 | 本页文件对象,空页为 `[]`。 |
+| `first_id` | string | 是 | 本页首个文件 ID,空页为 `null`。 |
+| `last_id` | string | 是 | 本页最后一个文件 ID,空页为 `null`;用作下一页 `after`。 |
+| `has_more` | boolean | 否 | 是否还有下一页。 |
+
+`limit` 默认 20、上限 100。`purpose`、`order` 和 `after` 按当前调用方的文件视图筛选与分页。
+
+## DELETE /v1/files/{file_id}:删除文件视图
+
+成功返回 **`200 OK` + `application/json`**,正文不是 `FileObject`,而是以下删除确认:
+
+```json
+{
+ "id": "file-result0123456789abcdef",
+ "object": "file",
+ "deleted": true
+}
+```
+
+三个字段均必带且不可为 `null`:`id` 为请求的文件 ID,`object` 固定为 `file`,`deleted` 为布尔值。
+这与取消 Task 不同:`DELETE /v1/tasks/{task_id}` 返回完整任务快照,不返回 `deleted`。
+
+## GET /v1/files/{file_id}/content:下载结果
+
+完整下载成功时返回 **`200 OK` 和文件二进制正文**,不是 JSON,也不是 Base64 字符串:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/zip
+Content-Disposition: attachment; filename="report.zip"
+
+<ZIP 文件二进制内容>
+```
+
+| 产物 | Content-Type | 正文格式 |
+|---|---|---|
+| default、LaTeX 或多格式 ZIP | `application/zip` | ZIP 文件字节。 |
+| 单独 DOCX | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` | DOCX 文件字节。 |
+| 单独 HTML | `text/html; charset=utf-8`(本地) | UTF-8 HTML 文件字节。 |
+
+下载建议文件名由 `Content-Disposition` 提供,非 ASCII 文件名可能使用标准的 `filename*` 编码。
+JSON 字段使用 `file_name`;HTTP 附件头的标准参数仍是 `filename` 或 `filename*`。ZIP 成员和输出格式见 [Tasks 输出格式与下载](tasks.md#输出格式与下载)。
+本地 API Server 直接流式返回产物;Router 代理 worker 的字节及下载头。Tasks 返回的 SaaS `result_url` 可能直接指向对象存储,不要求经过本路由。
+
+## 错误与保留期
+
+请求失败使用非 2xx 状态码和 JSON 错误对象,其字段为 `error.type/code/message/param`,详见 [响应与错误](responses.md)。
+常见情况为 `401 invalid_api_key`、`404 file_not_found`;尝试通过 `/content` 下载源文件返回 `403 feature_requires_api_key`,源文件下载不属于公共能力。
源文件通过 Tasks 的 JSON 清单和返回的上传链接创建。相同 hash 的有效缓存免传;不同文件名可以共享一份源字节,文件名和解析参数仍属于各自任务。
API Server 与 Router 默认保留 86400 秒,每 300 秒扫描。`--retention-seconds` 优先于 `MINERU_API_RETENTION_SECONDS`,0 禁用正常保留期清理。上传链接固定的一小时窗口不随该设置改变。
diff --git a/docs/next/api/responses.md b/docs/next/api/responses.md
index bb99a373..2cc107c1 100644
--- a/docs/next/api/responses.md
+++ b/docs/next/api/responses.md
@@ -7,16 +7,38 @@
## 成功响应
-成功响应直接返回资源对象,不增加统一外层 envelope。
+成功响应直接返回接口定义的对象,不增加统一外层 envelope。资源对象、分页列表、文件删除确认及二进制附件是不同的返回类型,不能统一按 Task 对象解析。
+
+| 接口 | 成功 HTTP | Content-Type | 正文 |
+|---|---|---|---|
+| `POST /v1/tasks` | 202 | `application/json` | 完整 `TaskStatusResponse`。 |
+| `GET /v1/tasks/{task_id}` | 200 | `application/json` | 完整 `TaskStatusResponse`,包括失败或取消后的状态。 |
+| `DELETE /v1/tasks/{task_id}` | 200 | `application/json` | 取消后的完整 `TaskStatusResponse`,不是删除确认。 |
+| 本地 `PUT /v1/tasks/{task_id}/uploads/{client_file_id}` | 200 | `application/json` | 当前完整 `TaskStatusResponse`。对象存储上传由存储服务定义响应。 |
+| `GET /v1/tasks` | 200 | `application/json` | 父任务摘要分页列表。 |
+| `GET /v1/files` | 200 | `application/json` | 文件元数据分页列表。 |
+| `GET /v1/files/{file_id}` | 200 | `application/json` | 完整 `FileObject`。 |
+| `DELETE /v1/files/{file_id}` | 200 | `application/json` | `id/object/deleted` 删除确认。 |
+| `GET /v1/files/{file_id}/content` | 200(完整下载) | 随产物格式 | ZIP、DOCX 或 HTML 文件字节。 |
+| 独立 `POST /v1/file_parse` | 200 / 202 | 附件 MIME / `application/json` | 等待成功返回附件;等待到期或零等待返回包装层 `StatusResponse`。 |
+| 独立 `GET /v1/file_parse/{request_id}` | 200 | `application/json` | 包装层 `StatusResponse`,不是 `TaskStatusResponse`。 |
+| 独立 `GET /v1/file_parse/{request_id}/result` | 200 | 随产物格式 | ZIP、DOCX 或 HTML 文件字节。 |
+
+Tasks 全部响应字段、类型、可空值及各接口完整 JSON 见 [Tasks](tasks.md#taskstatusresponse);Files 和下载响应见 [Files](files.md)。
+Health、Models、Tiers 见 [能力发现接口](health-models.md),用量见 [Usage](usage-limits.md),独立 Chat/Responses 协议见 [文档对话](chat.md)。
+独立包装服务的附件、202、状态查询和错误结构见 [file_parse 响应说明](file-parse.md#响应结构与格式)。
+JSON 正文使用 UTF-8;可空字段使用 JSON `null`,空列表使用 `[]`。例如删除一个 File 的成功响应为:
```json
{
- "task_id": "job_01HXYZ123ABCDEF",
- "status": "queued"
+ "id": "file-result0123456789abcdef",
+ "object": "file",
+ "deleted": true
}
```
-所有成功响应都应携带 `X-Request-Id`,便于客户端日志和服务端日志关联。
+当前 Python API Server 和 Router 不统一生成或返回 `X-Request-Id`;网关或公网部署提供请求追踪时,客户端可记录该响应头,不能把它作为上述共同响应的必带头。
+独立 file_parse 的成功附件和 202 响应明确携带 `X-Request-ID`;其状态查询和错误响应不统一附加该头,以专页列出的条件为准。
列表响应使用 OpenAI 风格分页 envelope:
@@ -34,21 +56,22 @@
| HTTP | 含义 |
|------|------|
-| 200 | 请求已完成,响应体是最终资源或当前资源。 |
-| 202 | 请求已接受,但任务仍在排队或执行。 |
+| 200 | HTTP 操作成功,响应体是当前资源、列表或附件;不表示异步 Task 或所有文件均解析成功。 |
+| 202 | Tasks 创建请求已接受,或 file_parse 等待结束/零等待后返回状态 JSON;具体任务状态以正文为准。 |
| 302 | 文件内容下载重定向到 CDN 或对象存储。 |
## 错误响应
-错误响应采用 OpenAI-compatible 结构:
+主 API Server 和 Router 的错误响应采用下面的 OpenAI-compatible 结构。
+独立 file_parse 使用 `error.code/message/upstream_status`,已有恢复记录时还返回状态字段;其错误格式以 [file_parse 错误响应](file-parse.md#错误响应) 为准。
```json
{
"error": {
"type": "invalid_request_error",
- "code": "file_too_large",
- "message": "File exceeds the 200MB limit.",
- "param": "file"
+ "code": "task_already_terminal",
+ "message": "Task is canceled",
+ "param": null
}
}
```
@@ -56,21 +79,22 @@
| 字段 | 类型 | 必带 | 说明 |
|------|------|:--:|------|
| `type` | string | 是 | 错误大类。 |
-| `code` | string 或 null | 否 | 机器可读的细分错误码。 |
+| `code` | string 或 null | 是 | 机器可读的细分错误码,无具体错误码时为 `null`。 |
| `message` | string | 是 | 人类可读描述,应包含必要上下文和修复建议。 |
-| `param` | string 或 null | 否 | 导致错误的参数名。 |
+| `param` | string 或 null | 否 | 导致错误的参数名;本地 API 无具体参数时返回 `null`,Router 代理层自身错误也可能省略此字段。 |
-所有错误响应都应携带 `X-Request-Id`。客户端应把该值记录到日志中;排查问题时,优先向服务端提供 request id。
+上例对应 `409 Conflict`;HTTP 错误的正文类型为 `application/json`。当前 Python API Server 和 Router 的错误对象均包含 `type/code/message`,客户端将缺省的 `param` 按 `null` 处理。
+请求级错误位于顶层 `error`;异步解析失败则通常通过查询接口的 `200` 响应及 `files[].error` 表达,详见 [Tasks 错误响应](tasks.md#各接口错误响应)。
## 请求追踪
-服务端必须在所有 API 响应中返回:
+请求追踪属于部署扩展。提供此能力的网关或服务可以在成功和失败响应中返回:
```http
X-Request-Id: req_01HXYZ123ABCDEF
```
-客户端可以在请求中传入自己的 request id,但服务端仍应返回服务端生成或确认后的 `X-Request-Id`。同一个外部请求在内部产生异步任务时,job 对象也应保留创建请求的 request id 以便追踪。
+该部署可以接收客户端传入的 request id,并返回生成或确认后的 `X-Request-Id`。当前 Python Tasks 响应没有 `request_id` 字段,也不承诺自动回传该头;不要据此推断 Task 创建幂等性。
## 幂等
@@ -112,13 +136,14 @@ Idempotency-Key: 7f5b7f7c-5c5a-4b2f-bb89-0c901c9a2d6a
| 403 | `permission_error` | `quota_exceeded` |
| 403 | `permission_error` | `feature_requires_api_key` |
| 403 | `permission_error` | `list_requires_api_key` |
-| 404 | `invalid_request_error` | `job_not_found`、`file_not_found`、`upload_not_found`、`model_not_found` |
-| 409 | `invalid_request_error` | `job_already_terminal`、`upload_not_ready`、`upload_already_terminal` |
+| 404 | `invalid_request_error` | `task_not_found`、`file_not_found`、`upload_not_found`、`model_not_found` |
+| 409 | `invalid_request_error` | `task_already_terminal`、`file_already_terminal` |
+| 410 | `invalid_request_error` | `upload_expired` |
| 413 | `invalid_request_error` | `file_too_large` |
| 429 | `rate_limit_error` | `rate_limit_exceeded` |
| 500 | `api_error` | `internal_error` |
| 503 | `api_error` | `service_unavailable` |
-| 503 | `engine_error` | `quality_tier_unavailable` |
+| 503 | `api_error` 或 `engine_error` | `quality_tier_unavailable`,以具体入口返回的错误大类为准。 |
完整错误分类见 [错误码体系](../errors.md)。
diff --git a/docs/next/api/tasks.md b/docs/next/api/tasks.md
index 2ae2b367..a99cc72b 100644
--- a/docs/next/api/tasks.md
+++ b/docs/next/api/tasks.md
@@ -5,6 +5,8 @@
每个文件就绪后立即执行,完成后在 `files[].result_url` 返回独立下载链接。
客户端不拼接存储路径,也不要求 SaaS 实现本地 Files API。
+快速定位:[响应字段](#taskstatusresponse) · [各接口成功响应](#各接口成功响应) · [错误响应](#各接口错误响应) · [输出格式与下载](#输出格式与下载)。
+
## 路由与请求
| 方法与路径 | 行为 |
@@ -12,7 +14,8 @@
| `POST /v1/tasks` | 仅接受 `application/json`,返回 `202` 和稳定 `task_id`。 |
| 返回的 `upload_method` 与 `upload_url` | 每个链接上传一个文件;本地使用 `PUT /v1/tasks/{task_id}/uploads/{client_file_id}`。 |
| `GET /v1/tasks/{task_id}` | 返回 `200`,包含总状态、逐文件状态、尚有效的上传链接和已完成文件的下载链接。 |
-| `DELETE /v1/tasks/{task_id}` | 取消未完成文件,保留已经完成文件的下载链接。 |
+| `DELETE /v1/tasks/{task_id}` | 返回 `200` 和取消后的完整任务对象,保留已经完成文件的下载链接。 |
+| `GET /v1/tasks` | 返回 `200` 和父任务摘要分页列表。 |
创建请求不再接受表单、multipart 或文件字节,其他 Content-Type 返回 `415`。
业务参数必须放在 JSON 主体中,POST 查询参数、未知字段、非法值返回 `400 invalid_request`。
@@ -76,6 +79,409 @@ curl --fail-with-body "$MINERU_API_URL/v1/tasks" \
未配置 API Key 的本地服务可省略 Authorization,四种输出格式均可用;启用服务认证后四种格式均需认证,没有额外的格式权限限制。
+## TaskStatusResponse
+
+`POST /v1/tasks`、`GET /v1/tasks/{task_id}`、`DELETE /v1/tasks/{task_id}` 的成功响应均为完整的 `TaskStatusResponse`。
+本地逐文件上传 `PUT /v1/tasks/{task_id}/uploads/{client_file_id}` 也返回同一结构。成功时直接返回对象,没有 `data` 或 `task` 外层包装。
+
+JSON 响应使用 `Content-Type: application/json`,正文为 UTF-8。下表列出的字段在当前本地 API Server 和 Router 响应中均会出现;可空字段输出 `null`,空集合输出 `[]` 或 `{}`,不以省略字段代替。客户端应忽略未来新增的响应字段。
+时间字符串使用 ISO-8601 UTC 格式,例如 `2026-10-23T04:00:00Z`;上传链接的 `expires_at` 单独使用 Unix 秒级整数。
+请求中的 `ocr_mode` 和顶层 `page_range` 不在响应顶层回显;逐文件页范围通过 `files[].page_range` 返回。
+
+### 顶层字段
+
+| 字段 | JSON 类型 | 可为 null | 含义 |
+|---|---|---|---|
+| `task_id` | string | 否 | 稳定的父任务 ID;是不透明标识,不代表内部逐文件执行 ID。 |
+| `status` | string | 否 | 父任务状态:`waiting_upload/queued/running/completed/partial/failed/canceled`。 |
+| `status_url` | string | 否 | 查询本任务的完整 URL;使用返回地址,不自行拼接。 |
+| `created_at` | string | 否 | 父任务创建时间。 |
+| `started_at` | string | 是 | 已知的最早逐文件执行开始时间;尚无执行开始记录时为 `null`。 |
+| `finished_at` | string | 是 | 父任务进入终态的时间;非终态时为 `null`,取消成功时也会填写。 |
+| `tier` | string | 是 | 任务级档位,非空时为 `flash/basic/standard/advanced`;文件实际采用的流程还受格式约束。 |
+| `output_formats` | array of string | 否 | 本次任务采用的输出格式,按首次出现去重。 |
+| `include_model_output` | boolean | 否 | 是否请求在 default ZIP 中附加可用模型输出。 |
+| `progress` | object | 否 | 文件计数,结构见下表。 |
+| `files` | array of object | 否 | 完整逐文件快照,顺序始终与创建请求一致,结构见下表。 |
+| `uploads` | array of object | 否 | 仍有效、尚未确认就绪的上传描述;无需上传或任务取消后为 `[]`。 |
+| `error` | object | 是 | 父任务级错误,结构为 `ErrorDetail`;逐文件失败应检查 `files[].error`。 |
+
+### progress:文件计数
+
+| 字段 | JSON 类型 | 含义 |
+|---|---|---|
+| `completed` | integer | 已成功完成解析和全部所选格式导出的文件数。 |
+| `failed` | integer | 已失败文件数,包含上传过期、下载、解析或导出失败。 |
+| `total` | integer | 输入文件总数,固定为创建请求的 `files` 长度。 |
+
+取消的文件不计入 `completed` 或 `failed`。存在排队、运行、等待上传或已取消文件时,`completed + failed` 可以小于 `total`,包括父任务已经为 `canceled` 的情况。
+
+### files[]:逐文件对象
+
+| 字段 | JSON 类型 | 可为 null | 含义 |
+|---|---|---|---|
+| `client_file_id` | string | 否 | 客户端显式提供或服务端补全的任务内唯一标识,创建后不变。 |
+| `file_name` | string | 否 | 创建时提交的逻辑文件名,保留扩展名;同名文件通过 ID 区分。 |
+| `bytes` | integer | 是 | 上传项的声明大小;URL 项可暂为 `null`,完整下载并校验后补齐实际字节数。 |
+| `url` | string | 是 | URL 输入保留原始下载地址;客户端上传项为 `null`。 |
+| `sha256sum` | string | 是 | 创建时声明的小写 SHA-256;URL 完整下载并校验后回填实际值,未声明 hash 的上传项可保持 `null`。 |
+| `page_range` | string | 是 | 归一化后的逐文件页范围,初始继承请求设置,整本初始为 `""`;执行后可回填实际页号范围。 |
+| `upload_status` | string | 否 | `pending/ready/not_required/expired`,与解析状态分别表达。 |
+| `file_id` | string | 是 | 本地/Router 上传项的源 Files ID,准备中可能为 `null`;URL 项为 `null`。这是源文件 ID,产物使用 `result_url` 下载。 |
+| `name` | string | 否 | 执行层回传的文件名;当前本地/Router 与 `file_name` 相同,仍保留此字段。 |
+| `status` | string | 否 | 单文件状态:`waiting_upload/queued/running/completed/failed/canceled`;没有 `partial`。 |
+| `parse` | object | 是 | 解析统计,尚无统计时为 `null`;非空结构见下表。 |
+| `result_url` | string | 是 | 结果完整保存后发布的唯一下载 URL;非 `completed` 文件为 `null`。 |
+| `error` | object | 是 | 该文件的错误详情;无错误时为 `null`。 |
+
+`upload_status` 的具体含义:`pending` 表示上传尚未确认,`ready` 表示源文件已经就绪,`not_required` 表示 URL 输入不需要客户端上传,`expired` 表示尚未完成上传的条目已过上传期限。
+取消尚未上传的文件后,其 `status` 为 `canceled`,`upload_status` 仍可能是 `pending`,但不再提供上传链接。
+
+### files[].parse:解析统计
+
+| 字段 | JSON 类型 | 可为 null | 含义 |
+|---|---|---|---|
+| `model_used` | string | 是 | 执行模型信息;当前本地解析实现为 `null`,不根据该字段推断 tier。 |
+| `duration_ms` | integer | 是 | 毫秒级文件执行耗时;当前实现包含源读取/下载、解析和导出,不含等待上传及排队时间。 |
+| `parser_version` | string | 是 | 执行 worker 的 MinerU 版本,不保证与 Router 的版本一致。 |
+
+### uploads[]:上传描述
+
+| 字段 | JSON 类型 | 含义 |
+|---|---|---|
+| `client_file_id` | string | 对应 `files[]` 中同 ID 的输入。 |
+| `upload_url` | string | 上传一个文件的完整 URL;签名地址必须原样使用。 |
+| `upload_method` | string | 当前为 `PUT`,客户端按返回值发送请求。 |
+| `upload_headers` | object | 字符串到字符串的映射;上传时发送这些请求头,不假定总是固定头集合。 |
+| `expires_at` | integer | Unix 秒级截止时间,创建任务后固定,查询不续期。 |
+
+### ErrorDetail:父任务或逐文件错误
+
+| 字段 | JSON 类型 | 可为 null | 含义 |
+|---|---|---|---|
+| `type` | string | 否 | 错误大类,例如 `invalid_request_error/engine_error/api_error`。 |
+| `code` | string | 是 | 机器可读错误码。 |
+| `message` | string | 否 | 人类可读错误说明,不作为客户端分支判断依据。 |
+| `param` | string | 是 | 关联参数,例如 `files.1.page_range`;无具体参数时为 `null`。 |
+
+`error=null` 不表示整个批次全部成功:父任务即使是 `partial/failed`,顶层 `error` 仍可为 `null`,错误位于具体文件的 `error` 中。
+
+## 各接口成功响应
+
+以下三个示例沿用同一批两个 HTML 输入:先创建任务,再上传并完成第一个文件,最后取消仍待上传的第二个文件。
+示例来自当前响应结构,ID、地址、时间和耗时为示意值;JSON 展示全部字段,不使用省略号。
+
+### POST /v1/tasks:创建任务
+
+成功返回 **`202 Accepted` + `application/json`**,正文为 `TaskStatusResponse`。`202` 只表示任务已接单,不表示文件已经解析成功。
+初始状态通常为 `waiting_upload`;URL 或缓存命中项可以直接进入 `queued`。`uploads` 只列出当前需要客户端上传的文件。
+
+请求示例:
+
+```json
+{
+ "files": [
+ {"file_name": "report.html", "bytes": 64},
+ {"file_name": "notes.html", "bytes": 64}
+ ],
+ "tier": "flash",
+ "output_formats": ["default"]
+}
+```
+
+完整响应:
+
+```json
+{
+ "task_id": "job_0123456789abcdef01234567",
+ "status": "waiting_upload",
+ "status_url": "http://127.0.0.1:8000/v1/tasks/job_0123456789abcdef01234567",
+ "created_at": "2026-10-23T04:00:00Z",
+ "started_at": null,
+ "finished_at": null,
+ "tier": "flash",
+ "output_formats": [
+ "default"
+ ],
+ "include_model_output": false,
+ "progress": {
+ "completed": 0,
+ "failed": 0,
+ "total": 2
+ },
+ "files": [
+ {
+ "client_file_id": "f1",
+ "file_name": "report.html",
+ "bytes": 64,
+ "url": null,
+ "sha256sum": null,
+ "page_range": "",
+ "upload_status": "pending",
+ "file_id": null,
+ "name": "report.html",
+ "status": "waiting_upload",
+ "parse": null,
+ "result_url": null,
+ "error": null
+ },
+ {
+ "client_file_id": "f2",
+ "file_name": "notes.html",
+ "bytes": 64,
+ "url": null,
+ "sha256sum": null,
+ "page_range": "",
+ "upload_status": "pending",
+ "file_id": null,
+ "name": "notes.html",
+ "status": "waiting_upload",
+ "parse": null,
+ "result_url": null,
+ "error": null
+ }
+ ],
+ "uploads": [
+ {
+ "client_file_id": "f1",
+ "upload_url": "http://127.0.0.1:8000/v1/tasks/job_0123456789abcdef01234567/uploads/f1",
+ "upload_method": "PUT",
+ "upload_headers": {
+ "Content-Type": "application/octet-stream"
+ },
+ "expires_at": 1792731600
+ },
+ {
+ "client_file_id": "f2",
+ "upload_url": "http://127.0.0.1:8000/v1/tasks/job_0123456789abcdef01234567/uploads/f2",
+ "upload_method": "PUT",
+ "upload_headers": {
+ "Content-Type": "application/octet-stream"
+ },
+ "expires_at": 1792731600
+ }
+ ],
+ "error": null
+}
+```
+
+### GET /v1/tasks/{task_id}:查询任务
+
+成功返回 **`200 OK` + `application/json`**,正文始终为 `TaskStatusResponse`,包括任务仍在运行、等待上传、部分失败、全部失败或已取消时。
+以下快照中,第一个文件已完成,可立即下载;第二个文件仍等待上传,所以父任务为 `waiting_upload`,`finished_at` 仍为 `null`。
+
+```json
+{
+ "task_id": "job_0123456789abcdef01234567",
+ "status": "waiting_upload",
+ "status_url": "http://127.0.0.1:8000/v1/tasks/job_0123456789abcdef01234567",
+ "created_at": "2026-10-23T04:00:00Z",
+ "started_at": "2026-10-23T04:00:01Z",
+ "finished_at": null,
+ "tier": "flash",
+ "output_formats": [
+ "default"
+ ],
+ "include_model_output": false,
+ "progress": {
+ "completed": 1,
+ "failed": 0,
+ "total": 2
+ },
+ "files": [
+ {
+ "client_file_id": "f1",
+ "file_name": "report.html",
+ "bytes": 64,
+ "url": null,
+ "sha256sum": null,
+ "page_range": "1",
+ "upload_status": "ready",
+ "file_id": "file-source0123456789abcdef",
+ "name": "report.html",
+ "status": "completed",
+ "parse": {
+ "model_used": null,
+ "duration_ms": 125,
+ "parser_version": "4.0.12"
+ },
+ "result_url": "http://127.0.0.1:8000/v1/files/file-result0123456789abcdef/content",
+ "error": null
+ },
+ {
+ "client_file_id": "f2",
+ "file_name": "notes.html",
+ "bytes": 64,
+ "url": null,
+ "sha256sum": null,
+ "page_range": "",
+ "upload_status": "pending",
+ "file_id": null,
+ "name": "notes.html",
+ "status": "waiting_upload",
+ "parse": null,
+ "result_url": null,
+ "error": null
+ }
+ ],
+ "uploads": [
+ {
+ "client_file_id": "f2",
+ "upload_url": "http://127.0.0.1:8000/v1/tasks/job_0123456789abcdef01234567/uploads/f2",
+ "upload_method": "PUT",
+ "upload_headers": {
+ "Content-Type": "application/octet-stream"
+ },
+ "expires_at": 1792731600
+ }
+ ],
+ "error": null
+}
+```
+
+### DELETE /v1/tasks/{task_id}:取消任务
+
+成功返回 **`200 OK` + `application/json`**,正文为取消后的完整 `TaskStatusResponse`,`status` 为 `canceled`,`uploads` 为 `[]`。
+这个接口取消未完成文件,不删除 Task 或已完成的结果;返回时后台不可中断计算或资源清理可能仍在收尾。
+已经成功或失败的文件保持原状态,成功文件继续提供 `result_url`。对任意已终结的父任务再次取消,返回 `409 task_already_terminal`。
+
+```json
+{
+ "task_id": "job_0123456789abcdef01234567",
+ "status": "canceled",
+ "status_url": "http://127.0.0.1:8000/v1/tasks/job_0123456789abcdef01234567",
+ "created_at": "2026-10-23T04:00:00Z",
+ "started_at": "2026-10-23T04:00:01Z",
+ "finished_at": "2026-10-23T04:00:03Z",
+ "tier": "flash",
+ "output_formats": [
+ "default"
+ ],
+ "include_model_output": false,
+ "progress": {
+ "completed": 1,
+ "failed": 0,
+ "total": 2
+ },
+ "files": [
+ {
+ "client_file_id": "f1",
+ "file_name": "report.html",
+ "bytes": 64,
+ "url": null,
+ "sha256sum": null,
+ "page_range": "1",
+ "upload_status": "ready",
+ "file_id": "file-source0123456789abcdef",
+ "name": "report.html",
+ "status": "completed",
+ "parse": {
+ "model_used": null,
+ "duration_ms": 125,
+ "parser_version": "4.0.12"
+ },
+ "result_url": "http://127.0.0.1:8000/v1/files/file-result0123456789abcdef/content",
+ "error": null
+ },
+ {
+ "client_file_id": "f2",
+ "file_name": "notes.html",
+ "bytes": 64,
+ "url": null,
+ "sha256sum": null,
+ "page_range": "",
+ "upload_status": "pending",
+ "file_id": null,
+ "name": "notes.html",
+ "status": "canceled",
+ "parse": null,
+ "result_url": null,
+ "error": null
+ }
+ ],
+ "uploads": [],
+ "error": null
+}
+```
+
+### PUT /v1/tasks/{task_id}/uploads/{client_file_id}:本地上传响应
+
+本地 API Server 和 Router 的上传成功返回 **`200 OK` + `application/json`**,正文仍为上面定义的完整 `TaskStatusResponse`。
+本次上传文件的 `upload_status` 为 `ready`,通常从 `uploads` 中移除并进入 `queued/running`;其他文件和已完成结果也包含在响应中。
+有效期内重复 PUT 已确认文件同样返回 `200` 和当前快照;上传链接到期后返回 `410`,不会重新读取或覆盖源字节。
+
+SaaS 返回的上传目标可能是独立对象存储:其成功状态码和响应体由该存储服务决定,不要求返回 Tasks JSON。
+通用客户端应接受目标服务的成功响应,随后查询 `status_url` 确认就绪情况,不把对象存储上传响应直接作为任务状态解析。
+
+### GET /v1/tasks:列出父任务
+
+成功返回 **`200 OK` + `application/json`**,正文为 `TaskListResponse`,不是完整的 `TaskStatusResponse`:
+
+```json
+{
+ "object": "list",
+ "data": [
+ {
+ "task_id": "job_0123456789abcdef01234567",
+ "status": "canceled",
+ "created_at": "2026-10-23T04:00:00Z",
+ "file_count": 2
+ }
+ ],
+ "first_id": "job_0123456789abcdef01234567",
+ "last_id": "job_0123456789abcdef01234567",
+ "has_more": false
+}
+```
+
+| 字段 | JSON 类型 | 可为 null | 含义 |
+|---|---|---|---|
+| `object` | string | 否 | 固定为 `list`。 |
+| `data` | array of object | 否 | 父任务摘要;没有结果时为 `[]`。 |
+| `data[].task_id` | string | 否 | 父任务 ID。 |
+| `data[].status` | string | 否 | 与完整任务对象相同的父任务状态枚举。 |
+| `data[].created_at` | string | 否 | ISO-8601 UTC 创建时间。 |
+| `data[].file_count` | integer | 否 | 该任务的输入文件总数。 |
+| `first_id` | string | 是 | 本页第一项 task ID;空页为 `null`。 |
+| `last_id` | string | 是 | 本页最后一项 task ID;空页为 `null`,作为下一页 `after`。 |
+| `has_more` | boolean | 否 | 是否还有下一页。 |
+
+列表不返回 `files/uploads/progress/result_url`;需要详情时逐任务查询。筛选与分页参数见本页“父任务列表与缓存”。
+
+## 各接口错误响应
+
+请求级失败返回对应非 2xx 状态码和 `Content-Type: application/json`,正文是仅包含顶层 `error` 的 JSON 对象,其值为上文的 `ErrorDetail`,不返回成功任务对象。
+例如重复取消任务返回 **`409 Conflict`**:
+
+```json
+{
+ "error": {
+ "type": "invalid_request_error",
+ "code": "task_already_terminal",
+ "message": "Task is canceled",
+ "param": null
+ }
+}
+```
+
+| 接口 | HTTP | 常见 code | 场景 |
+|---|---|---|---|
+| POST | 400 | `invalid_request`、`page_range_invalid` | 字段、ID、页范围等非法,包括旧字段和新旧混传。 |
+| POST | 415 | `invalid_request` | 请求不是 `application/json`。 |
+| POST | 503 | `quality_tier_unavailable`、`server_shutting_down` 或模型预加载错误码 | 当前部署无法接单。 |
+| GET 详情 / DELETE / 本地 PUT | 404 | `task_not_found` | task 不存在、记录已清理或不属于当前调用方。 |
+| DELETE | 409 | `task_already_terminal` | 父任务已经成功、部分成功、失败或被取消;包括取消前刷新时刚进入终态。 |
+| 本地 PUT | 400 | `upload_size_mismatch`、`file_hash_mismatch`、`upload_interrupted` | 上传校验失败或传输中断;未过期时可查询后重传。 |
+| 本地 PUT | 404 | `upload_not_found` | task 中不存在该 `client_file_id`。 |
+| 本地 PUT | 409 | `task_already_terminal`、`file_already_terminal` | 任务已取消或文件已不接受上传。 |
+| 本地 PUT | 410 | `upload_expired` | 固定上传窗口已过期。 |
+| GET 列表 | 400 / 404 | `invalid_request` / `task_not_found` | 筛选参数非法,或 `after` 游标不存在、已清理或越权。 |
+| 所有受保护接口 | 401 | `invalid_api_key` | 服务启用认证,但调用方未提供有效凭据。 |
+
+Router 或网关还可能返回远端依赖相关的 5xx 错误;错误格式及部署扩展见 [响应与错误](responses.md)。
+本地 API 和上述任务错误示例包含 `param: null`;Router 代理层自身产生的错误也可能省略 `param`,客户端按 `null` 处理。
+异步文件下载、解析或导出失败通常通过查询接口的 **`200` 快照和 `files[].error`** 表达;不要把 HTTP `200` 等同于任务成功,也不要仅凭顶层 `error` 判断全部文件是否成功。
+
## URL、缓存与独立上传
URL 输入同样先创建 JSON 任务:
@@ -116,16 +522,7 @@ URL 输入同样先创建 JSON 任务:
状态响应只有元数据,不内联 Markdown、JSON 或结果文件字节。
`files` 按原清单顺序返回,使用 `client_file_id` 对应输入,不依赖文件名唯一性。
-| 字段 | 说明 |
-|---|---|
-| `task_id`、`status`、`status_url` | 稳定父任务标识、聚合状态、查询地址。 |
-| `files[].upload_status` | `pending/ready/not_required/expired`。 |
-| `files[].status` | `waiting_upload/queued/running/completed/failed/canceled`,包含导出过程。 |
-| `files[].result_url` | 该文件产物完整保存前为 `null`;`completed` 时为唯一下载链接。 |
-| `files[].error` | 该文件的上传过期、下载、解析或导出错误。 |
-| `uploads` | 仍有效的待上传项:`client_file_id/upload_url/upload_method/upload_headers/expires_at`。 |
-| `progress` | 文件计数:`completed/failed/total`,`total` 固定为清单长度;取消不计为解析失败。 |
-| `error` | 父任务级错误;逐文件错误应读取 `files[].error`。 |
+完整字段、类型和可空约束见 [TaskStatusResponse](#taskstatusresponse),下面说明状态聚合规则。
Task 顶层没有 `result_url`;`files[]` 不暴露底层 `output_files`。
已完成文件可以在父任务仍为 `running/queued/waiting_upload` 时下载。