MinerU/docs/next/api/tasks.md

V1 Tasks：JSON 清单、逐文件上传与下载

/v1/tasks 是本地 API Server、Router 和 SaaS 的共同异步客户端契约。 客户端用 JSON 创建任务，按 files[].upload 上传缺失文件，再通过固定路径 GET /v1/tasks/{task_id} 轮询。 每个文件就绪后立即执行，完成后在 files[].result_url 返回独立下载链接。 客户端不拼接存储路径，也不要求 SaaS 实现本地 Files API。

快速定位：响应字段 · 各接口成功响应 · 错误响应 · 输出格式与下载。

路由与请求

方法与路径	行为
POST /v1/tasks	仅接受 application/json，返回 202 和稳定 task_id。
PUT 返回的 files[].upload.url	每个链接上传一个文件；本地使用 PUT /v1/tasks/{task_id}/uploads/{file_id}。
GET /v1/tasks/{task_id}	返回 200，包含总状态、逐文件状态、尚有效的上传链接和已完成文件的下载链接。
POST /v1/tasks/{task_id}/cancel	返回 200 CancelTaskResponse，包含所有文件的终态及已经完成文件的下载链接。

创建请求不再接受表单、multipart 或文件字节，其他 Content-Type 返回 415。 业务参数必须放在 JSON 主体中，POST 查询参数、未知字段、非法值返回 400 invalid_request。 上传文件的 PUT 仍发送原始字节，使用返回的 files[].upload.headers；签名 URL 必须原样使用。 Task ID 是父任务标识；内部逐文件执行 ID 不属于公共契约。 不提供任务记录或产物的公开 DELETE 接口；旧 DELETE 取消入口不保留别名，认证通过后返回 405。

JSON 字段	默认值	说明
files	必填	1–100 个文件组成的 JSON 数组，不接受 JSON 字符串。
tier	服务默认值	flash/basic/standard/advanced，受部署能力约束。
ocr_mode	auto	auto/txt/ocr。
page_range	整本	全局 PDF 页范围，支持 1-5、r1、all 等现有语法。
output_formats	["default"]	非空列表，值为 default/docx/html/latex 中一个或多个；重复值按首次出现去重。

ModelJson 仅用于内部解析与后处理，不属于 HTTP 或 SDK 结果。请求携带已删除的 include_model_output 字段（包括值为 false）返回 400。

每个清单条目包含：

字段	必填	说明
file_name	是	逻辑文件名，保留扩展名；不同条目允许同名。
url	否	HTTP(S) 文件下载地址，受部署来源策略约束；省略或 null 表示客户端上传。
bytes	条件	上传项必填；URL 项可省略或为 null。提供时必须是严格正整数。
sha256sum	否	64 位小写十六进制 SHA-256；用于完整性校验，上传项还用于源文件缓存预检。
page_range	否	逐文件 PDF 页范围，未提供时继承全局值；非 PDF 仍只支持整本解析。

服务端为每个输入分配唯一的 file_id，请求不得包含 client_file_id 或 file_id，即使值为 null 也返回 400 invalid_request。 创建响应的 files 顺序与输入一致，客户端先按原始顺序绑定 ID，随后使用 ID 关联上传、查询、取消和结果。同名输入或相同内容仍获得不同 ID。 该 ID 从创建到结果下载保持不变；在本地和 Router 中，产物注册后的 Files ID 与它一致。产物生成前只预留 ID，对 Files 元数据和内容接口的访问返回 404 file_not_found。 源缓存引用不属于公共 ID；跨任务可共享源字节，但每次任务独立生成产物。Router 内部映射各层生成的 ID，对客户端始终保留本层 ID。

先从真实文件生成 JSON 请求（文件 ID 统一由服务端生成）：

python3 - a.pdf b.pdf > task.json <<'PY'
import hashlib
import json
from pathlib import Path
import sys

files = []
for value in sys.argv[1:]:
    path = Path(value)
    hasher = hashlib.sha256()
    with path.open('rb') as source:
        for chunk in iter(lambda: source.read(1024 * 1024), b''):
            hasher.update(chunk)
    files.append({
        'file_name': path.name,
        'bytes': path.stat().st_size,
        'sha256sum': hasher.hexdigest(),
    })
print(json.dumps({'files': files, 'tier': 'flash', 'ocr_mode': 'txt',
                  'output_formats': ['default', 'latex']}, ensure_ascii=False))
PY

curl --fail-with-body "$MINERU_API_URL/v1/tasks" \
  -H "Authorization: Bearer $MINERU_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @task.json

未配置 API Key 的本地服务可省略 Authorization，四种输出格式均可用；启用服务认证后四种格式均需认证，没有额外的格式权限限制。

响应模型

创建、详情、取消和上传确认使用独立模型。成功响应直接返回对象，没有 data 或 task 包装。GET 新增详情字段不会自动进入其他响应。

接口	模型	顶层字段
POST 创建	CreateTaskResponse	task_id/status/files。
GET	TaskDetailResponse	task_id/status/created_at/output_formats/progress/files，以及有值的 started_at/finished_at/error。
POST cancel	CancelTaskResponse	task_id/status/finished_at/files。
本地 PUT	UploadFileResponse	task_id/file_id/status，其中 status 是本次上传文件的状态。

这些成功响应递归省略值为 null 的可选字段，保留 0/false/[]/{}，例如 progress.failed=0 和 upload.headers={}。OpenAPI 将可省略字段标为非必填。 每次响应是该接口当前的完整快照；缺少可选字段表示当前没有该值，不能沿用上一次响应的上传地址或结果信息。客户端应忽略未来新增的字段。 共享的非成功错误响应，以及 Files、file_parse 自身的响应，保持各自现有空值规则。

JSON 正文使用 UTF-8。时间字符串使用 ISO-8601 UTC；上传链接 expires_at 使用 Unix 秒级整数。 请求中的 tier/ocr_mode/page_range 和逐文件 sha256sum/page_range 不作响应回显；实际档位位于成功文件的 parse.tier。 客户端保留配置 API 基址的代理前缀，并追加 /v1/tasks/{URL 编码后的 task_id} 查询；Tasks 不返回 status_url。

创建回执的 files[]

每项必带 file_id/file_name/status；只有当前需要客户端上传时才带 upload。POST 不返回文件大小、解析统计或结果链接，即使文件已经完成也通过 GET 获取详情。

查询详情的顶层字段

字段	JSON 类型	必带	含义
task_id	string	是	稳定的父任务 ID，不代表内部逐文件执行 ID。
status	string	是	waiting-file/pending/running/completed/partial/failed/canceled。
created_at	string	是	父任务创建时间。
started_at	string	否	已知最早的逐文件执行开始时间，无记录时省略。
finished_at	string	否	父任务进入终态的时间，非终态时省略。
output_formats	array of string	是	本次输出格式，按首次出现去重。
progress	object	是	必带整数 completed/failed/total，零值保留。
files	array of object	是	全部文件的当前详情，始终保持创建请求顺序。
error	object	否	父任务级错误，逐文件失败见 files[].error。

completed 计数表示解析及全部所选格式均成功的文件数；failed 包含上传过期、下载、解析和导出失败；total 固定为输入文件数。取消文件不计入 completed 或 failed。

查询详情的 files[]

字段	JSON 类型	必带	含义
file_id	string	是	服务端分配的公共文件 ID，创建后不变。
file_name	string	是	输入逻辑文件名，同名文件通过 ID 区分。
status	string	是	waiting-file/pending/running/completed/failed/canceled，没有 partial。
bytes	integer	否	输入大小，URL 下载前未知时省略，校验后补齐实际字节数。
url	string	否	URL 输入的原始下载地址，上传输入省略。
upload	object	否	当前可执行的上传动作，服务端准备、输入就绪或终结时省略。
parse	object	否	成功完成后的实际档位和解析统计。
result_url	string	否	completed 文件完整产物的下载地址。
error	object	否	文件错误详情，无错误时省略。

waiting-file 包括等待上传、接收、对象存储确认、URL 下载及完整性校验；pending 表示输入已就绪并等待解析资源；running 包含解析、导出和结果保存。 只在 waiting-file 且存在 upload 时上传；没有 upload 时只轮询，不能据此认为输入已经就绪。成功 PUT 后即使仍为 waiting-file 也不重复传输。 只有上传失败、查询确认仍需上传且链接有效时才有界重试。上传过期使用 failed 和 error.code=upload_expired。

取消回执的 files[]

每项必带 file_id/file_name/status，status 只会是 completed/failed/canceled。成功文件附带 parse/result_url，失败文件附带 error；不包含 upload、输入大小或来源 URL。 取消操作保留任务和已完成产物，返回后可直接使用成功文件的下载链接。底层不可中断计算和资源清理可能仍在收尾，迟到结果不会覆盖已公布的取消终态。

files[].parse：解析统计

成功后的实际 tier 来自结果元数据，不以请求 tier 代替。PDF 和图片沿用多档位规则，HTML、Office 等原生文档使用 flash，同一批次可出现不同档位。

字段	JSON 类型	必带	含义
tier	string	是	实际执行档位：flash/basic/standard/advanced。
duration_ms	integer	否	已知的毫秒级耗时，包含源读取/下载、校验、解析和导出，不含等待上传、准备名额及解析队列时间。
parser_version	string	否	已知的执行 worker 版本，不保证与 Router 版本一致。

files[].upload：待上传描述

固定使用 PUT 上传原始字节；对象不重复携带 file_id，也不返回 upload_method。查询仍提供当前有效的上传入口。

字段	JSON 类型	含义
url	string	完整上传地址，签名 URL 原样使用。
headers	object	必带的字符串请求头映射，允许为空对象。
expires_at	integer	固定的 Unix 秒级截止时间，查询不续期。

ErrorDetail：父任务或逐文件错误

成功快照中的 error 必带 type/message，有值时附带 code/param；空值仍省略。缺少顶层 error 不代表所有文件成功，partial/failed 的原因可能只在逐文件 error 中。 HTTP 非成功错误 envelope 保持现有契约，见下文。

各接口成功响应

以下完整示例使用同一批两个 HTML 输入，ID、地址、时间和耗时均为示意值。

POST /v1/tasks：创建任务

返回 202 Accepted 和 CreateTaskResponse。202 表示接单，具体状态以响应为准。请求：

{
  "files": [
    {
      "file_name": "report.html",
      "bytes": 64
    },
    {
      "file_name": "notes.html",
      "bytes": 64
    }
  ],
  "tier": "flash",
  "output_formats": [
    "default"
  ]
}

创建回执：

{
  "task_id": "job_0123456789abcdef01234567",
  "status": "waiting-file",
  "files": [
    {
      "file_id": "file-111111111111111111111111",
      "file_name": "report.html",
      "status": "waiting-file",
      "upload": {
        "url": "http://127.0.0.1:8000/v1/tasks/job_0123456789abcdef01234567/uploads/file-111111111111111111111111",
        "headers": {
          "Content-Type": "application/octet-stream"
        },
        "expires_at": 1792731600
      }
    },
    {
      "file_id": "file-222222222222222222222222",
      "file_name": "notes.html",
      "status": "waiting-file",
      "upload": {
        "url": "http://127.0.0.1:8000/v1/tasks/job_0123456789abcdef01234567/uploads/file-222222222222222222222222",
        "headers": {
          "Content-Type": "application/octet-stream"
        },
        "expires_at": 1792731600
      }
    }
  ]
}

GET /v1/tasks/{task_id}：查询任务

返回 200 OK 和 TaskDetailResponse，包括任务失败、取消等终态。以下第一个文件完成、第二个仍待上传，父任务仍为 waiting-file，finished_at 省略：

{
  "task_id": "job_0123456789abcdef01234567",
  "status": "waiting-file",
  "created_at": "2026-10-23T04:00:00Z",
  "started_at": "2026-10-23T04:00:01Z",
  "output_formats": [
    "default"
  ],
  "progress": {
    "completed": 1,
    "failed": 0,
    "total": 2
  },
  "files": [
    {
      "file_id": "file-111111111111111111111111",
      "file_name": "report.html",
      "bytes": 64,
      "status": "completed",
      "parse": {
        "tier": "flash",
        "duration_ms": 125,
        "parser_version": "4.0.12"
      },
      "result_url": "http://127.0.0.1:8000/v1/files/file-111111111111111111111111/content"
    },
    {
      "file_id": "file-222222222222222222222222",
      "file_name": "notes.html",
      "status": "waiting-file",
      "upload": {
        "url": "http://127.0.0.1:8000/v1/tasks/job_0123456789abcdef01234567/uploads/file-222222222222222222222222",
        "headers": {
          "Content-Type": "application/octet-stream"
        },
        "expires_at": 1792731600
      },
      "bytes": 64
    }
  ]
}

POST /v1/tasks/{task_id}/cancel：取消任务

无需请求体。例如：

curl --fail-with-body -X POST "$MINERU_API_URL/v1/tasks/$TASK_ID/cancel" \
  -H "Authorization: Bearer $MINERU_API_KEY"

返回 200 OK 和 CancelTaskResponse。已成功或失败的文件保留终态，其余文件转为 canceled；已终结的父任务再次取消返回 409 task_already_terminal。

{
  "task_id": "job_0123456789abcdef01234567",
  "status": "canceled",
  "finished_at": "2026-10-23T04:00:03Z",
  "files": [
    {
      "file_id": "file-111111111111111111111111",
      "file_name": "report.html",
      "status": "completed",
      "parse": {
        "tier": "flash",
        "duration_ms": 125,
        "parser_version": "4.0.12"
      },
      "result_url": "http://127.0.0.1:8000/v1/files/file-111111111111111111111111/content"
    },
    {
      "file_id": "file-222222222222222222222222",
      "file_name": "notes.html",
      "status": "canceled"
    }
  ]
}

PUT /v1/tasks/{task_id}/uploads/{file_id}：本地上传确认

本地 API Server 和 Router 返回 200 OK 和 UploadFileResponse，不返回整份任务详情。本次文件完成保存及校验后进入 pending/running，最新详情通过 GET 获取。

{
  "task_id": "job_0123456789abcdef01234567",
  "file_id": "file-111111111111111111111111",
  "status": "pending"
}

有效期内重复 PUT 已确认文件仍返回当前文件回执，且不读取或覆盖源字节；上传窗口到期后返回 410。 SaaS 的上传目标可能是独立对象存储：通用客户端接受成功的 2xx 响应，不要求其返回本地 PUT 回执，随后查询 Tasks 确认就绪。

各接口错误响应

请求级失败返回对应非 2xx 状态码和 Content-Type: application/json，正文是仅包含顶层 error 的 JSON 对象，其值为上文的 ErrorDetail，不返回成功任务对象。 例如重复取消任务返回 409 Conflict：

{
  "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 详情 / POST cancel / 本地 PUT	404	task_not_found	task 不存在、记录已清理或不属于当前调用方。
POST cancel	409	task_already_terminal	父任务已经成功、部分成功、失败或被取消；包括取消前刷新时刚进入终态。
本地 PUT	400	upload_size_mismatch、file_hash_mismatch、upload_interrupted	上传校验失败或传输中断；未过期时可查询后重传。
本地 PUT	404	upload_not_found	task 中不存在该 file_id。
本地 PUT	409	task_already_terminal、file_already_terminal	任务已取消或文件已不接受上传。
本地 PUT	410	upload_expired	固定上传窗口已过期。
所有受保护接口	401	invalid_api_key	服务启用认证，但调用方未提供有效凭据。

Router 或网关还可能返回远端依赖相关的 5xx 错误；错误格式及部署扩展见 响应与错误。 本地 API 和上述任务错误示例包含 param: null；Router 代理层自身产生的错误也可能省略 param，客户端按 null 处理。 异步文件下载、解析或导出失败通常通过查询接口的 200 快照和 files[].error 表达；不要把 HTTP 200 等同于任务成功，也不要仅凭顶层 error 判断全部文件是否成功。

URL、缓存与独立上传

URL 输入同样先创建 JSON 任务：

{
  "files": [
    {"file_name": "document.pdf", "url": "https://example.com/download?signature=example"},
    {"file_name": "other.pdf", "bytes": 12345}
  ],
  "output_formats": ["html"]
}

• URL 项保持 waiting-file 和 upload 省略，由服务端下载和校验；确认有效后进入 pending。不生成客户端上传链接，不接受 PUT，不等待其他文件上传。
• URL 保留原始签名地址，使用逻辑 file_name 识别类型；不要求 HEAD 或 Content-Length。下载后回填实际 bytes；请求提供的大小/hash 必须匹配，但响应不回显 hash。URL 每次下载，不用 hash 缓存跳过下载。
• 上传项 hash 命中时直接进入 pending，不返回上传链接；未命中或无 hash 时返回该文件的链接。上传后仍计算 hash、校验大小并对源字节去重。
• 缓存只复用源文件，不复用不匹配的解析结果；每个文件使用本次解析参数独立执行。
• 每个上传项校验完成即排队，不需要客户端发送完成确认。等待客户端上传不预占 worker；worker 上 URL 下载与校验使用受控准备阶段，不占解析并发。

一小时上传窗口

所有上传链接的 expires_at 固定为创建时起 3600 秒，采用 Unix 秒。查询不会延长或换发链接。 到期后新 PUT 返回 410 upload_expired，包括对已经确认文件的重复 PUT。

截止前已受理的上传可以继续传完并校验，该文件仍处于 waiting-file，不会被过期扫描中止。 尚未受理上传的文件到期后变为 status=failed，逐文件错误码为 upload_expired。URL 下载不受客户端上传截止时间影响，沿用来源下载超时。 在途上传中断且已经过期时，同样进入失败终态；补交须创建新任务。 上传截止时间不限制已上传文件的排队、解析或导出时间。

有效期内，一个文件中断或校验失败可以从头重传，其他文件的状态不受影响。 重复 PUT 已确认文件不读取或覆盖源字节，并发请求也只提交一次解析。 上传响应丢失时先查询：进入 pending/running/completed 后跳过上传；仍为 waiting-file 且 upload 省略 时只轮询；有有效上传目标时才有限重试。 不支持单文件分块断点续传。

总状态与逐文件状态

状态响应只有元数据，不内联 Markdown、JSON 或结果文件字节。 files 按原清单顺序返回，使用 file_id 对应输入，不依赖文件名唯一性。

各响应字段、类型及省略规则见 响应模型，下面说明状态聚合规则。

Task 顶层没有 result_url；files[] 不暴露底层 output_files。 已完成文件可以在父任务仍为 running/pending/waiting-file 时下载。

总状态优先级如下：

条件	status
存在运行中的文件，包括导出阶段	running
没有运行文件，存在排队文件	pending
剩余未完成文件全部处于文件准备阶段	waiting-file
所有文件成功	completed
所有文件终结，成功与失败并存	partial
所有文件终结，无成功文件	failed
用户取消任务	canceled

因此，第一个文件解析完成而第二个文件尚未上传时，总状态可以由 running 回到 waiting-file，第一个文件的下载链接仍然有效。 取消只停止未完成的文件，已经成功或失败的文件保持原状态；重复取消终态任务返回 409。

输出格式与下载

一个输入文件对应一个下载链接，与该 Task 有多少输入文件无关。

output_formats	下载内容
["default"]	ZIP：markdown.md、middle_json.json、structured_content.json、images/。
["docx"]	图片内嵌的单个 .docx。
["html"]	图片内嵌的单个 .html。
["latex"]	ZIP：document.tex、images/。
多个不同值	一个 ZIP，平铺对应文件，不嵌套 ZIP。

多格式 ZIP 内 DOCX 和 HTML 分别为 document.docx、document.html。 default 和 LaTeX 共用同一套物化图片及 images/ 引用；无图片时目录可为空。 DOCX 和 HTML 即使放入多格式 ZIP，也保持图片内嵌。 default 不包含 model_output.json；不生成跨输入文件的总 ZIP 或批次 manifest.json。

每个输入只解析一次，基于同一结果生成所选格式。全部所选格式完成并保存后才发布该文件的 completed 和链接。 任一格式失败，该文件为 failed/result_packaging_failed 且不返回结果链接，不提供不完整产物；其他文件继续执行。 导出复用已物化素材，不重新打开源文件或修改原语义树。图片缺失时报错，不交付引用失效的 HTML 单文件。 HTML 的“单文件”保证图片内嵌，公式脚本仍沿用现有 renderer 的行为。

• SaaS 返回对象存储签名地址，结果字节不经过网关。
• 本地返回 /v1/files/{file_id}/content 的完整地址，流式输出已保存产物。
• Router 映射自身 Files 地址并流式代理 worker，不暴露内部 worker 地址。

轮询及重复下载不重新渲染或打包。下载签名过期时，可在结果保留期内再次查询任务取得有效地址；这与不可续期的上传链接不同。 已经完成的结果不会因为其他文件仍在等待而提前回收，保留期从父 Task 清理完成后开始。 认证只附加到 API 同源请求；对象存储及跨源重定向不得携带 MinerU API Key。

客户端示例

scripts/http_task_example.sh 调用同目录 Python 脚本，仅需要 Python 3.10+ 标准库。 创建请求不会自动重试；文件传输有界重试，先查询状态再处理响应丢失。 下载使用临时文件、验证对应格式后原子保存，成功文件保存在 RESULT_DIR/<file_id>/<输入文件主名>.<扩展名>。

MINERU_API_URL=http://127.0.0.1:8000 \
  bash scripts/http_task_example.sh a.pdf b.pdf

OUTPUT_FORMATS=default,latex,docx RESULT_DIR=results \
MINERU_API_URL=http://127.0.0.1:8000 \
  bash scripts/http_task_example.sh a.pdf b.pdf

# 使用首次提交的文件列表和顺序恢复，不重新创建任务。
TASK_ID=job_... MINERU_API_URL=http://127.0.0.1:8000 \
  bash scripts/http_task_example.sh a.pdf b.pdf

配置	默认值	说明
MINERU_API_URL	必填	API 或 Router 基地址。
MINERU_API_KEY	空	服务认证。
SEND_HASH	1	0 时不计算或提交 hash。
TASK_ID	空	恢复已有任务，只处理仍有上传动作的文件。
MINERU_TIER、OCR_MODE、PAGE_RANGE	服务默认 / auto / 整本	解析参数。
OUTPUT_FORMATS	default	逗号分隔，转为 JSON 数组。
RESULT_DIR	results	逐文件结果目录。
MAX_POLLS、POLL_INTERVAL	300、1	查询预算和间隔秒数。
CONNECT_TIMEOUT、REQUEST_TIMEOUT	10、600	连接与单次传输超时秒数。
MINERU_PYTHON	python3	Python 可执行文件。

退出码为 0（全部成功）、2（部分成功）、1（失败或取消）、124（轮询预算耗尽）。已下载的成功结果保留。 轮询超时不取消服务端任务。UPLOAD_MODE 与 RESULT_FILE 已删除。

部署、Router 与迁移

本地不设固定客户端上传大小或 PDF 页数上限；usage.limits.max_file_size_bytes/max_pages_per_file 为 null。 URL 下载沿用服务的来源策略：默认 HTTPS；HTTP 需启用 --allow-http-source，下载超时默认 60 秒、大小默认 200 MiB。 任务记录和上传索引仍为进程内状态，重启不保证恢复。

Router 按就绪文件独立选择 worker 并预占负载，同一父 Task 可使用多个 worker。 URL 交给 worker 下载，客户端上传字节按 worker 的缓存预检结果传输。 Router 的源缓存使用按调用方隔离的私有引用，不等待或转发 worker 的源 Files ID；结果仍通过 Files 映射下载。私有源引用在父任务完成清理后开始保留期，过期独立回收，活动传输继续保护字节。 健康接口的 features.task_output_formats 声明 Tasks 格式，sources 为 upload/url。 Router 创建任务前使用候选 worker 的受保护 /v1/usage 校验认证，不调用列表接口，不预占解析名额。 不声明新 Tasks 能力的旧 worker 不参与 Tasks 调度，更新时应先更新 worker，再更新 Router 和客户端。 Router 使用有界、可续租的内部结果租约保护 worker 产物，上传窗口不受结果租约影响；Router 丢失后租约会自行结束。已完成任务按 worker 并行续租，每轮网络等待最多 10 秒，避免失联 worker 阻塞其他 worker 的结果保留。

创建请求仅接受 files 和 file_name，不兼容 manifest、filename；新旧字段混传同样返回 400。Tasks 响应及 Files 详情统一使用 file_name。 任务和文件列表接口已移除；使用创建响应中的 task_id 和固定查询路由恢复任务，按 files[].result_url 下载。合法认证下 GET /v1/tasks 返回 405，GET /v1/files 返回 404。 这是同一 /v1 下的破坏性变更：先停收请求并排空在途任务，再协调更新 worker、Router、SDK、file_parse 包装服务及其他客户端；SaaS 由部署方同步对齐。

本次协议不保留旧表单、直传或 markdown/middle_json/structured_content/zip Tasks 格式别名。 客户端应改用 JSON、files[].result_url 及逐文件保存方式。 API Server 和 Router 不提供 /v1/file_parse、/v1/tasks/{task_id}/result。 需要同步单文件调用时，独立启动 file_parse 包装服务，由它调用本页的共同 Tasks 契约。 SaaS Go 服务和对象存储配置由部署方按此共同契约实现，不属于本地 Python 服务代码。

源文件缓存

SDK 即使连接同机也计算 hash 并提交清单。缓存有效且已完成上传的同 hash 后续免传；并发首次上传允许重复传输但源字节去重。默认缓存保留 24 小时、每 5 分钟扫描，沿用 retention 配置；活动任务与传输引用保护字节。缓存过期或服务重启后允许重新上传。