# MinerU 云端执行参考

使用 API 前核对 [官方文档](https://mineru.net/apiManage/docs)，接口、限额与响应字段可能改变。没有 API 配置时优先网页，不要求新手部署服务器。

## 精准 API

- Token 来自用户在 API 管理页创建的凭据。约定由执行环境的 `MINERU_API_TOKEN` 提供；不要求用户粘贴到对话，不从浏览器提取。
- 本地图片使用 `POST https://mineru.net/api/v4/file-urls/batch` 申请上传地址，JSON 包含 `files` 数组和 `model_version: "vlm"`；文件条目包含带扩展名的 `name`、稳定的 `data_id` 和 `is_ocr: true`。保留公式、表格识别。批量上限以当前接口专节为准；文档总览与专节不一致时采用较小值。
- API 请求使用 Bearer Token；成功响应检查 HTTP 状态及业务 `code`，保存 `data.batch_id`。将每份文件的二进制 PUT 到对应 `data.file_urls`，不要把 Token 附到这些签名上传地址，也不要把文件路径文本当作文件内容。上传后自动进入解析，无须重复提交。
- 用 `GET https://mineru.net/api/v4/extract-results/batch/{batch_id}` 查询。按 `data_id` 对应原图；逐项检查 `state`，只下载 `done` 项的 `full_zip_url`，记录 `failed` 的原因。
- 每次请求设超时，轮询间隔约 10–20 秒，遵守服务返回的退避提示。一次等待约 15 分钟仍未完成时保存进度并报告待续，不重建任务。
- 原始 ZIP 分文件保存。解压前确认每个成员路径留在对应 raw 子目录，拒绝绝对路径、越界路径和链接。解析实际 Markdown 与图片目录，不假定所有版本的产物名称都相同。

官方另有免 Token 的 Agent 轻量 API，但结果能力与精准解析不同。它不是完整图文包的无条件替代品；仅在确认图片可完整保留、用户接受该路线时采用。

## 网页路径

从 [MinerU](https://mineru.net/) 当前界面寻找文档解析入口。实际观察上传格式、数量限制与导出选项后操作，下载包含 Markdown 和图片资源的完整结果。记录任务或结果页面地址以便恢复。仅有文本结果时须从原图补齐插图，不能静默丢图。

若网页登录或文件选择需要用户操作，具体说明所需动作，完成可独立进行的盘点和排序，保留任务状态。不要把服务登录问题描述成识别模型不可用。