V1 Tasks:JSON 清单、逐文件上传与下载
/v1/tasks 是本地 API Server、Router 和 SaaS 的共同异步客户端契约。
/v1/tiers 只约束 PDF/图片。所有正常可用的兼容服务均支持现有原生文档格式并固定使用 flash,无需额外能力字段。Router 转发原生文件时省略 tier;PDF/图片转发已确定的档位。
客户端用 JSON 创建任务,按 files[].upload 上传缺失文件,再通过固定路径 GET /v1/tasks/{task_id} 轮询。
每个文件就绪后立即执行,完成后在 files[].result_url 返回独立下载链接。
客户端不拼接存储路径,也不要求 SaaS 实现本地 Files API。
第一次 HTTP 请求 · 创建请求 · 响应字段 · 共用响应对象 · 各接口成功响应 · 错误响应 · 输出格式与下载。
启动与认证
mineru-kit api-server --host 127.0.0.1 --port 8000 --tier auto
服务的 /docs 和 /openapi.json 提供当前部署的接口定义。配置 API Key 时,API 请求使用 Authorization: Bearer <API_KEY>;未配置 Key 的本地服务可省略该头。请求基地址可带反向代理路径前缀。
路由概览
| 方法与路径 | 成功响应 | 用途 |
|---|---|---|
POST /v1/tasks |
202,CreateTaskResponse |
提交 JSON 清单。 |
PUT files[].upload.url |
本地/Router 为 200,UploadFileResponse |
上传一个文件的原始字节;对象存储接受其成功 2xx 响应。 |
GET /v1/tasks/{task_id} |
200,TaskDetailResponse |
查询完整状态快照。 |
POST /v1/tasks/{task_id}/cancel |
200,CancelTaskResponse |
取消未完成文件,无需请求体。 |
本地上传路径为 /v1/tasks/{task_id}/uploads/{file_id},客户端应使用返回的完整 URL。没有任务/文件列表、公开 DELETE 或批次结果接口。主 API Server 和 Router 不提供 /v1/file_parse。
Task ID 是父任务标识;内部逐文件执行 ID 不属于公共契约。 不提供任务记录或产物的公开 DELETE 接口;旧 DELETE 取消入口不保留别名,认证通过后返回 405。
未配置 API Key 的本地服务可省略 Authorization,四种输出格式均可用;启用服务认证后四种格式均需认证,没有额外的格式权限限制。
创建任务请求
以下字段仅用于 POST /v1/tasks 的 JSON 请求体。创建请求不再接受表单、multipart 或文件字节,其他 Content-Type 返回 415。
业务参数必须放在 JSON 主体中,创建接口的查询参数、未知字段、非法值返回 400 invalid_request。
顶层请求字段
| JSON 字段 | 默认值 | 说明 |
|---|---|---|
files |
必填 | 1–100 个文件组成的 JSON 数组,不接受 JSON 字符串。 |
tier |
服务默认值 | 可选,仅对 PDF/图片生效;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。
tier:默认选择与文件作用范围
省略 tier 或传入 JSON null 时,服务端从支持的档位中按 standard → basic → flash → advanced 选择第一个;仅服务只开放 advanced 时默认选择 advanced。
仅开放 flash 的服务可以直接接收未指定 tier 的 PDF/图片;仅开放 advanced 时,未指定 tier 默认使用 advanced。
请求包含 PDF/图片且显式提供 tier 时,服务支持该档位就原样使用;不支持则在创建阶段返回 400 invalid_request,error.param="tier",整个请求不接单、不分配上传链接,也不自动升档或降档。
空字符串和未知枚举始终是参数错误,包括纯原生文档请求。
Office、HTML 等已支持的原生文档固定使用 flash,不受请求 tier 影响。纯原生文档批次忽略合法的显式 tier,不要求服务开放该 PDF/图片档位;原生解析是所有正常可用服务的必备能力,不从 /v1/tiers 判断。
例如,部署只对 PDF/图片开放 standard 时:
| 输入 | 请求 tier | 执行结果 |
|---|---|---|
| PDF + DOCX | 省略或 null |
PDF 使用 standard,DOCX 使用 flash。 |
| PDF + DOCX | standard |
PDF 使用 standard,DOCX 使用 flash。 |
| PDF + DOCX | basic 或 advanced |
创建时返回 400。 |
| 只有 DOCX | basic 或 advanced |
DOCX 使用 flash。 |
可在一个请求中混合提交文件,客户端无需预先拆分档位:
{
"files": [
{"file_name": "report.pdf", "bytes": 12000},
{"file_name": "contract.docx", "bytes": 8000}
]
}
服务在接单时确定并保存选档,等待上传、排队和后续转发不重新选择默认值。Router 按每个文件的有效档位选择 worker,并显式传给下游;原档位后来不可用时按文件报告失败,不自动改档。
实际执行档位始终读取成功文件的 files[].parse.tier,同一批次允许不同档位。
该规则也适用于 HTTP SDK 和 file_parse 提交的单文件 Tasks;直接本地解析和 Doclib 保持各自的选档策略。
files[]:输入清单
请求体的 files 数组中,每个条目包含以下字段:
| 字段 | 必填 | 说明 |
|---|---|---|
file_name |
是 | 1–1024 个字符的逻辑文件名(basename),保留扩展名,不含目录;不同条目允许同名。 |
url |
否 | HTTP(S) 文件下载地址,受部署来源策略约束;省略或 null 表示客户端上传。 |
bytes |
条件 | 上传项必填;URL 项可省略或为 null。提供时必须是严格正整数。 |
sha256sum |
否 | 64 位小写十六进制 SHA-256;用于完整性校验,上传项还用于源文件缓存预检。 |
page_range |
否 | 逐文件 PDF 页范围,未提供时继承全局值;非 PDF 仍只支持整本解析。 |
file_name 对上传和 URL 输入使用相同校验:不允许 /、反斜杠、冒号、Unicode Cc 类控制字符,也不能恰好为 . 或 ..。中文、空格、.report.csv 和 report..csv 等名称允许使用;服务不裁剪空格、不解码百分号,也不把路径自动截成文件名。
例如 ../report.csv、C:\input\report.csv 和 report.csv:stream 均返回 400 invalid_request,error.param 为 files.<index>.file_name。清单中任一名称非法,整个请求在分配任务、文件 ID 和上传链接前失败,Router 不向下游转发。
这是对路径形式名称的接口收紧:自定义客户端应在本地提取 basename 后提交;官方 SDK 已使用 path.name。逻辑文件名用于格式识别和展示,不指定服务器的读写路径;服务端继续使用生成的标识或内容哈希存储文件。CLI 的本地输入路径仍支持 ../ 和绝对路径。multipart file_parse 保留先去除目录、再校验文件名的兼容行为。
文件 ID 与输入关联
服务端为每个输入分配唯一的 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
对应的完整 JSON 请求和创建回执见 创建任务成功响应。
响应模型
创建、详情、取消和上传确认使用独立模型。成功响应直接返回对象,没有 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 取消 | 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。
POST 创建响应
POST /v1/tasks 返回 202 Accepted 和 CreateTaskResponse。202 表示接单,具体状态以响应为准。完整示例见 创建任务成功响应。
创建回执的顶层字段
| 字段 | JSON 类型 | 必带 | 含义 |
|---|---|---|---|
task_id |
string | 是 | 稳定的父任务 ID,用于后续查询、上传和取消。 |
status |
string | 是 | 当前任务总状态:waiting-file/pending/running/completed/partial/failed/canceled。 |
files |
array of object | 是 | 每个输入的文件 ID、当前状态和上传动作,顺序与创建请求一致。 |
创建回执的 files[]
| 字段 | JSON 类型 | 必带 | 含义 |
|---|---|---|---|
file_id |
string | 是 | 服务端分配的公共文件 ID,创建后不变。 |
file_name |
string | 是 | 输入逻辑文件名,同名文件通过 ID 区分。 |
status |
string | 是 | 当前文件状态:waiting-file/pending/running/completed/failed/canceled,没有 partial。 |
upload |
object | 否 | 仅在当前需要客户端上传时返回,见 待上传描述。 |
创建回执不返回文件大小、解析统计或结果链接,即使文件已经完成也通过 GET 获取详情。
GET 查询响应
GET /v1/tasks/{task_id} 返回 200 OK 和 TaskDetailResponse,包括任务失败、取消等终态。完整示例见 查询任务成功响应。
客户端保留配置 API 基址的代理前缀,并追加 /v1/tasks/{URL 编码后的 task_id} 查询;Tasks 不返回 status_url。
查询详情的顶层字段
| 字段 | 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 | 是 | 逐文件进度计数,字段见本节下表。 |
files |
array of object | 是 | 全部文件的当前详情,始终保持创建请求顺序。 |
error |
object | 否 | 有父任务级错误时返回 ErrorDetail,逐文件失败见 files[].error。 |
查询详情的 progress
| 字段 | JSON 类型 | 必带 | 含义 |
|---|---|---|---|
completed |
integer | 是 | 解析及全部所选格式均成功的文件数。 |
failed |
integer | 是 | 失败文件数,包含上传过期、下载、解析和导出失败。 |
total |
integer | 是 | 固定为创建请求中的输入文件数。 |
三个计数均保留零值。取消文件不计入 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 | 否 | 文件错误详情,结构为 ErrorDetail,无错误时省略。 |
waiting-file 包括等待上传、接收、对象存储确认、URL 下载及完整性校验;pending 表示输入已就绪并等待解析资源;running 包含解析、导出和结果保存。
只在 waiting-file 且存在 upload 时上传;没有 upload 时只轮询,不能据此认为输入已经就绪。成功 PUT 后即使仍为 waiting-file 也不重复传输。
只有上传失败、查询确认仍需上传且链接有效时才有界重试。上传过期使用 failed 和 error.code=upload_expired。
POST 取消响应
POST /v1/tasks/{task_id}/cancel 无需请求体,返回 200 OK 和 CancelTaskResponse。已成功或失败的文件保留终态,其余文件转为 canceled;已终结的父任务再次取消返回 409 task_already_terminal。完整示例见 取消任务成功响应。
取消回执的顶层字段
| 字段 | JSON 类型 | 必带 | 含义 |
|---|---|---|---|
task_id |
string | 是 | 被取消的父任务 ID。 |
status |
string | 是 | 固定为 canceled。 |
finished_at |
string | 是 | 父任务进入取消终态的时间。 |
files |
array of object | 是 | 全部文件的终态,顺序与创建请求一致。 |
取消回执的 files[]
| 字段 | JSON 类型 | 必带 | 含义 |
|---|---|---|---|
file_id |
string | 是 | 服务端分配的公共文件 ID,与创建回执一致。 |
file_name |
string | 是 | 输入逻辑文件名,同名文件通过 ID 区分。 |
status |
string | 是 | 文件终态,只会是 completed/failed/canceled。 |
parse |
object | 否 | 成功文件附带实际档位和 解析统计。 |
result_url |
string | 否 | 成功文件附带完整产物的下载地址。 |
error |
object | 否 | 失败文件附带 ErrorDetail,无错误时省略。 |
取消回执不包含上传动作、输入大小或来源 URL。 取消操作保留任务和已完成产物,返回后可直接使用成功文件的下载链接。底层不可中断计算和资源清理可能仍在收尾,迟到结果不会覆盖已公布的取消终态。
PUT 上传确认响应
向返回的 files[].upload.url 发送原始字节,使用 files[].upload.headers,签名 URL 必须原样使用。
本地 API Server 和 Router 的 PUT /v1/tasks/{task_id}/uploads/{file_id} 返回 200 OK 和 UploadFileResponse。完整示例见 本地上传确认成功响应。
| 字段 | JSON 类型 | 必带 | 含义 |
|---|---|---|---|
task_id |
string | 是 | 本次上传所属的父任务 ID。 |
file_id |
string | 是 | 本次上传文件的公共 ID,与创建回执一致。 |
status |
string | 是 | 本次文件的当前状态:waiting-file/pending/running/completed/failed/canceled,不是父任务总状态。 |
本次文件完成保存及校验后进入 pending/running;响应不包含 files 或其他任务详情,最新详情通过 GET 获取。
有效期内重复 PUT 已确认文件仍返回当前文件回执,且不读取或覆盖源字节;上传窗口到期后返回 410 upload_expired。
SaaS 的上传目标可能是独立对象存储:通用客户端接受成功的 2xx 响应,不要求其返回上述本地 PUT 回执,随后查询 Tasks 确认就绪。
共用响应对象
以下对象只在各接口字段表标注的位置出现,不代表每种响应都包含这些字段。
files[].upload:待上传描述
适用于 POST 创建、GET 查询 的 files[].upload。
固定使用 PUT 上传原始字节;对象不重复携带 file_id,也不返回 upload_method。查询仍提供当前有效的上传入口。
| 字段 | JSON 类型 | 必带 | 含义 |
|---|---|---|---|
url |
string | 是 | 完整上传地址,签名 URL 原样使用。 |
headers |
object | 是 | 字符串请求头映射,允许为空对象。 |
expires_at |
integer | 是 | 固定的 Unix 秒级截止时间,查询不续期。 |
files[].parse:解析统计
适用于 GET 查询、POST 取消 的 files[].parse。
成功后的实际 tier 来自结果元数据,不以请求 tier 代替。PDF 和图片沿用多档位规则,HTML、Office 等原生文档使用 flash,同一批次可出现不同档位。
| 字段 | JSON 类型 | 必带 | 含义 |
|---|---|---|---|
tier |
string | 是 | 实际执行档位:flash/basic/standard/advanced。 |
duration_ms |
integer | 否 | 已知的毫秒级耗时,包含源读取/下载、校验、解析和导出,不含等待上传、准备名额及解析队列时间;未知时省略。 |
parser_version |
string | 否 | 已知的执行 worker 版本,不保证与 Router 版本一致;未知时省略。 |
ErrorDetail:父任务或逐文件错误
成功快照中适用于 GET 查询 的顶层 error 和 files[].error,以及 POST 取消 的 files[].error。
| 字段 | JSON 类型 | 必带 | 含义 |
|---|---|---|---|
message |
string | 是 | 错误说明。 |
code |
string | 是 | 稳定的非空错误码,供程序判断错误原因。 |
param |
string 或 null | 否 | 关联参数路径,例如 files.0.page_range;有值时返回,无值时省略。接收端允许缺省或 null。 |
缺少顶层 error 不代表所有文件成功,partial/failed 的原因可能只在逐文件 error 中。
HTTP 非成功响应也使用相同的 ErrorDetail,外层为 {"error": ...}。所有错误均不包含 type,code/message 必带,param 无值时省略;完整示例及错误码见 各接口错误响应。
各接口成功响应
以下完整示例使用同一批两个 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": {
"code": "task_already_terminal",
"message": "Task is canceled"
}
}
| 接口 | 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、Router 和 SaaS 使用同一错误结构。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。
URL 目标必须解析为公网单播地址。worker 在连接前校验全部 IPv4/IPv6 地址,并固定连接已校验的 IP。
内网、回环、链路本地、云元数据及特殊地址会使对应文件以 unsupported_source 失败。
下载使用直连并拒绝重定向。部署中的 HTTP_PROXY、HTTPS_PROXY 和 ALL_PROXY 对 URL 来源下载无效,
HTTPS 证书校验继续读取 SSL_CERT_FILE / SSL_CERT_DIR。内网文档可以通过客户端上传。
使用 Fake-IP 代理时,应让 worker 的 DNS 返回真实公网地址;198.18.0.0/15 等保留网段会被拒绝。
对外提供解析服务时,应配置 --api-key 并限制 worker 的出站网络访问。
任务记录和上传索引仍为进程内状态,重启不保证恢复。
动态 upstream 管理与级联
运行服务时如何注册、查询、平滑移除节点及组建多层 Router,见 Router 部署与管理。
协议迁移
创建请求仅接受 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 配置;活动任务与传输引用保护字节。缓存过期或服务重启后允许重新上传。