PaddleOCR API 文档 - OCR 与文档解析接口

开始使用

概览

每个文件或 URL 创建一个任务，轮询任务状态，完成后下载 ZIP。接口为异步处理。Pro 月付和年付支持 API，Free 不支持。

API 基础地址

https://YOUR_API_HOST/api/open/v1

将 YOUR_API_HOST 替换为你的 API 域名；下方接口均使用此基础地址。示例中的 ID 和签名链接为占位值。

POST/tasks创建任务 GET/tasks/{id}获取任务结果 GET/tasks获取任务列表

鉴权与请求头

每个 API 请求携带 Authorization: Bearer 加 Pro API 密钥。通过页面的 API 密钥按钮查看或重置。密钥为 sk- 加 24 个随机字母或数字，区分大小写；用户登录 JWT 不能用于这些接口。

字段	类型	必填	含义与规则
`Authorization`	`string`	是	Bearer 加 Pro API 密钥，所有接口必填。

请求头

Authorization: Bearer sk-YOUR_API_KEY

密钥保存在你的服务端，不要放进公开前端代码、仓库或文件下载请求。下载使用独立签名地址。重置后旧密钥立即失效；API 调用还需要 Pro 会员有效。

完整调用示例

替换 API 域名、设置 MINERU_API_KEY，并准备 paper.pdf。示例只上传一次，每 3 秒查询，最多等待 30 分钟，完成后将 ZIP 写入磁盘。轮询超时只是客户端停止等待，不会取消服务端任务，可用任务 ID 继续查询。Python 需要 requests，Node.js 需要 20+，cURL 示例使用 Bash 和 jq。

Python

# pip install requests
import os
import time
import requests

API = "https://YOUR_API_HOST/api/open/v1"
headers = {"Authorization": "Bearer " + os.environ["MINERU_API_KEY"]}
with open("paper.pdf", "rb") as source:
    response = requests.post(API + "/tasks", headers=headers, files={"file": ("paper.pdf", source, "application/pdf")},
        data={"force_ocr": "true", "extra_formats": '["docx","html"]'}, timeout=120)
response.raise_for_status()
body = response.json()
if body["code"] != 0:
    raise RuntimeError(body["code"] + ": " + body["msg"])
task_id = body["data"]["task_id"]

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    response = requests.get(API + "/tasks/" + task_id, headers=headers, timeout=30)
    response.raise_for_status()
    body = response.json()
    if body["code"] != 0:
        raise RuntimeError(body["code"] + ": " + body["msg"])
    data = body["data"]
    task = data["task"]
    if task["status"] == "completed":
        url = data["results"].get("full_zip_url")
        if not url:
            raise RuntimeError("ZIP unavailable; check expires_at")
        # Download separately: do not send the API key to the download host.
        with requests.get(url, stream=True, timeout=120) as download:
            download.raise_for_status()
            with open("result.zip", "wb") as output:
                for chunk in download.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.zip")
        break
    if task["status"] in {"failed", "expired"}:
        raise RuntimeError(task["status"] + ": " + task["error"])
    time.sleep(3)
else:
    raise TimeoutError("Polling timed out; task ID: " + task_id)

API 接口

创建任务

POST/api/open/v1/tasks

只有一个创建接口：POST /api/open/v1/tasks。选择一种输入方式：用 multipart/form-data 直传文件，或用 JSON 提交 source_url。两种方式都返回 data.task_id，后续使用相同的任务查询流程。每次成功提交都会创建新任务。

化学模式仅接受 PDF 和图片，不支持 force_ocr 和 extra_formats。

方式一：直传文件

直接向 API 服务器上传单个文件。由 HTTP 客户端自动设置 multipart boundary，不要手写 Content-Type。表单仅接受 file 和可选 force_ocr、extra_formats。服务端校验实际字节数和单位后保存并入队，不需要额外的上传完成请求。

请求体参数 · multipart/form-data

字段	类型	必填	含义与规则
`file`	`binary`	是	仅一个文件，文件名必须有支持的后缀。
`parse_type`	`string (0 \| 1)`	否	0：通用文档（默认）；1：化学分子结构识别。默认值: `0`
`force_ocr`	`string (true \| false)`	否	true / false; 仅对 PDF 生效。开启后忽略已有文字层并使用 OCR；关闭时自动判断。其他格式不受影响。默认值: `false`
`extra_formats`	`string (JSON)`	否	JSON 数组字符串，例如 ["docx","html"]，仅 html、docx、latex。默认值: `[]`

请求示例 · cURL

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -F '[email protected]' \
  -F 'force_ocr=true' \
  -F 'extra_formats=["docx","html"]'

响应字段 · 200 OK

HTTP 200 表示任务创建成功。code 为 0，msg 为 ok，data 只包含 task_id。通过查询接口获取状态和结果。

字段	类型	含义与规则
`code`	`integer`	任务创建成功时为 0。
`data.task_id`	`string (UUID)`	创建时 data.task_id 返回的任务 UUID。
`msg`	`string`	任务创建成功时为 ok。

响应示例

{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436"
  },
  "msg": "ok"
}

方式二：提交 URL

使用 JSON，不与 multipart 上传混用。source_url 可以是公网 HTTP/HTTPS 文档、图片或 HTML 链接。源站需提供正数 Content-Length，并能从响应头或文件名确定支持格式；信息缺失、冲突或变化会使任务失败。拒绝内网、含账号密码的 URL、压缩或分块响应，最多 5 次重定向。创建后为 queued，获取失败在后续 task.error 中查看。

请求体参数 · application/json

字段	类型	必填	含义与规则
`source_url`	`string`	是	公网 HTTP/HTTPS 源地址，需要通过元数据和大小校验。
`parse_type`	`integer (0 \| 1)`	否	0：通用文档（默认）；1：化学分子结构识别。默认值: `0`
`force_ocr`	`boolean`	否	true / false; 仅对 PDF 生效。开启后忽略已有文字层并使用 OCR；关闭时自动判断。其他格式不受影响。默认值: `false`
`extra_formats`	`string[]`	否	数组而非 JSON 字符串，可选 html、docx、latex；Markdown 和 JSON 默认已包含。默认值: `[]`

请求示例 · cURL

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"source_url":"https://example.com/paper.pdf","force_ocr":true,"extra_formats":["docx","html"]}'

响应字段 · 200 OK

HTTP 200 表示任务创建成功。code 为 0，msg 为 ok，data 只包含 task_id。通过查询接口获取状态和结果。

字段	类型	含义与规则
`code`	`integer`	任务创建成功时为 0。
`data.task_id`	`string (UUID)`	创建时 data.task_id 返回的任务 UUID。
`msg`	`string`	任务创建成功时为 ok。

响应示例

{
  "code": 0,
  "data": {
    "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436"
  },
  "msg": "ok"
}

化学结构识别 · cURL

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -F '[email protected]' \
  -F 'parse_type=1'

获取任务列表

GET/api/open/v1/tasks

网页和 API 任务统一分页，按创建时间倒序。每项只包含 task_id、status、credits、created_at，以及 file 的 name、size、mime_type、source_type。详细文件信息、失败原因、到期时间及结果地址通过详情获取。page_size 为 1–100，超出使用 20；page 小于 1 时使用 1。

查询参数

字段	类型	必填	含义与规则
`page`	`integer`	否	从 1 开始；无效或小于 1 时使用 1。默认值: `1`
`page_size`	`integer`	否	每页 1–100 条，无效值使用 20。默认值: `20`
`search`	`string`	否	按文件名搜索全部本人任务，最多 255 个字符。
`status`	`string`	否	可选状态：queued、running、completed、failed、expired；多个状态用英文逗号分隔。

请求示例 · cURL

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks?page=1&page_size=20" \
  -H "Authorization: Bearer $API_KEY"

响应字段 · 200 OK

字段	类型	含义与规则
`data.items`	`TaskSummary[]`	任务摘要列表，每项只包含 TaskSummary 表中的字段。
`data.has_more`	`boolean`	是否还有下一页。
`data.page`	`integer`	从 1 开始；无效或小于 1 时使用 1。
`data.page_size`	`integer`	每页 1–100 条，无效值使用 20。

响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
        "parse_type": 0,
        "status": "completed",
        "credits": 2,
        "created_at": "2026-10-12T07:04:05Z",
        "file": {
          "name": "paper.pdf",
          "size": 12345,
          "mime_type": "application/pdf",
          "source_type": "upload"
        }
      }
    ],
    "has_more": false,
    "page": 1,
    "page_size": 20
  }
}

TaskSummary

字段	类型	含义与规则
`task_id`	`string (UUID)`	创建时 data.task_id 返回的任务 UUID。
`parse_type`	`integer (0 \| 1)`	0：通用文档（默认）；1：化学分子结构识别。
`status`	`string`	整体任务状态，见任务状态表。
`credits`	`integer`	计费数量：PDF 页数、PPT 幻灯片数、Excel 工作表数；Word、HTML 和图片各计 1。URL 文件检查完成前为 0。
`created_at`	`string (RFC3339)`	记录创建时间，RFC3339。
`file.name`	`string`	原文件名；URL 任务初始可能显示源站域名。
`file.size`	`integer (int64)`	实际保存字节数，URL 下载前为 0。
`file.mime_type`	`string`	保存的 MIME 类型，获取中可能为空。
`file.source_type`	`string`	upload 或 url。

获取任务结果

GET/api/open/v1/tasks/{id}

读取 data.task.status 判断状态。results 始终是字典：queued、running、failed、expired 时为空，completed 时包含文档结果地址，ZIP 地址为 results.full_zip_url。失败任务返回 HTTP 200、code task_failed、msg 为失败原因；过期返回 code result_expired。

路径参数

字段	类型	必填	含义与规则
`id`	`string (UUID)`	是	创建时 data.task_id 返回的任务 UUID。

请求示例 · cURL

curl --fail-with-body "https://YOUR_API_HOST/api/open/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

响应字段 · 200 OK

字段	类型	含义与规则
`data.task`	`Task`	Task 对象，详情查询成功时返回。
`data.file`	`File`	输入 File 对象，URL 元数据可能尚未就绪。
`data.results`	`object`	results 固定为字典，包含文件和图片地址；未完成、失败或过期时为空字典。

处理中的响应 · running

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task": {
      "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
      "parse_type": 0,
      "status": "running",
      "credits": 2,
      "force_ocr": true,
      "expires_at": "2026-10-19T07:04:05Z",
      "error": "",
      "created_at": "2026-10-12T07:04:05Z"
    },
    "file": {
      "name": "paper.pdf",
      "size": 12345,
      "mime_type": "application/pdf",
      "suffix": "pdf",
      "source_type": "upload",
      "source_url": ""
    },
    "results": {}
  }
}

响应示例 · completed

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task": {
      "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
      "parse_type": 0,
      "status": "completed",
      "credits": 2,
      "force_ocr": true,
      "expires_at": "2026-10-19T07:04:05Z",
      "error": "",
      "created_at": "2026-10-12T07:04:05Z"
    },
    "file": {
      "name": "paper.pdf",
      "size": 12345,
      "mime_type": "application/pdf",
      "suffix": "pdf",
      "source_type": "upload",
      "source_url": ""
    },
    "results": {
      "original_url": "https://downloads.example.com/uploads/4001a517-cd93-47a6-a56a-e53d2a0828df/aa0e6ab6-44f3-4554-b459-b62fe4c6b437.pdf?token=SIGNED_TOKEN",
      "markdown_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/preview/markdown.md?token=SIGNED_TOKEN",
      "middle_json_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/preview/middle_json.json?token=SIGNED_TOKEN",
      "structured_json_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/preview/structured_content.json?token=SIGNED_TOKEN",
      "images": {
        "images/001.jpg": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/preview/images/001.jpg?token=SIGNED_TOKEN"
      },
      "full_zip_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/exports/6b0e6ab6-44f3-4554-b459-b62fe4c6b439.zip?token=SIGNED_TOKEN"
    }
  }
}

任务失败的响应 · HTTP 200

{
  "code": "task_failed",
  "msg": "MinerU job ended: failed",
  "data": {
    "task": {
      "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
      "parse_type": 0,
      "status": "failed",
      "credits": 2,
      "force_ocr": true,
      "expires_at": "2026-10-19T07:04:05Z",
      "error": "MinerU job ended: failed",
      "created_at": "2026-10-12T07:04:05Z"
    },
    "file": {
      "name": "paper.pdf",
      "size": 12345,
      "mime_type": "application/pdf",
      "suffix": "pdf",
      "source_type": "upload",
      "source_url": ""
    },
    "results": {}
  }
}

化学结构识别 · 已完成

{
  "code": 0,
  "msg": "ok",
  "data": {
    "task": {
      "task_id": "a90e6ab6-44f3-4554-b459-b62fe4c6b436",
      "parse_type": 1,
      "status": "completed",
      "credits": 2,
      "force_ocr": false,
      "expires_at": "2026-10-19T07:04:05Z",
      "error": "",
      "created_at": "2026-10-12T07:04:05Z"
    },
    "file": {
      "name": "paper.pdf",
      "size": 12345,
      "mime_type": "application/pdf",
      "suffix": "pdf",
      "source_type": "upload",
      "source_url": ""
    },
    "results": {
      "original_url": "https://downloads.example.com/uploads/4001a517-cd93-47a6-a56a-e53d2a0828df/aa0e6ab6-44f3-4554-b459-b62fe4c6b437.pdf?token=SIGNED_TOKEN",
      "json_url": "https://downloads.example.com/results/a90e6ab6-44f3-4554-b459-b62fe4c6b436/molecular_structures.json?token=SIGNED_TOKEN"
    }
  }
}

Task

字段	类型	含义与规则
`task_id`	`string (UUID)`	创建时 data.task_id 返回的任务 UUID。
`parse_type`	`integer (0 \| 1)`	0：通用文档（默认）；1：化学分子结构识别。
`status`	`string`	整体任务状态，见任务状态表。
`credits`	`integer`	计费数量：PDF 页数、PPT 幻灯片数、Excel 工作表数；Word、HTML 和图片各计 1。URL 文件检查完成前为 0。
`force_ocr`	`boolean`	true / false; 仅对 PDF 生效。开启后忽略已有文字层并使用 OCR；关闭时自动判断。其他格式不受影响。
`expires_at`	`string \| null (RFC3339)`	任务保留截止时间，结果或失败写入前可能为 null。
`error`	`string`	处理错误或恢复说明，无错误时为空。
`created_at`	`string (RFC3339)`	记录创建时间，RFC3339。

File

字段	类型	含义与规则
`name`	`string`	原文件名；URL 任务初始可能显示源站域名。
`size`	`integer (int64)`	实际保存字节数，URL 下载前为 0。
`mime_type`	`string`	保存的 MIME 类型，获取中可能为空。
`suffix`	`string`	小写后缀，不含点号，获取中可能为空。
`source_type`	`string`	upload 或 url。
`source_url`	`string`	用户提交的源 URL，上传文件时为空。

results

字段	类型	含义与规则
`original_url`	`string`	原文件签名地址。
`json_url`	`string`	化学识别 JSON 下载地址，仅 parse_type=1 时返回。
`markdown_url`	`string`	用于预览读取的原生 markdown.md 签名地址。
`middle_json_url`	`string`	middle_json.json 签名地址，包含页码、结构及归一化坐标。
`structured_json_url`	`string`	structured_content.json 的签名地址；没有对应文件时不返回此字段。
`images`	`Record<string, string>`	原生相对路径到签名图片地址的映射，无图片时为空对象。
`full_zip_url`	`string`	results.full_zip_url 是 API 任务最终 ZIP 的签名下载地址，仅完成且未过期时返回。

参考说明

输入格式与限制

Pro 单个文档最大 200 MiB、图片最大 50 MiB、最多 500 页或计费单位。API 与网页共用账号额度：每天 5 单位及每月 1000 单位，优先使用每日额度。校验通过后冻结，基础解析结果保存成功后扣除；确认解析失败或停止后释放。发布／导出失败不退已成功解析的额度；任务执行失败或超时自动释放尚未扣除的额度。导出不重复扣费。

输入格式	文件名后缀	计费单位
PDF	`.pdf`	PDF 物理页数
Word	`.doc, .docx`	每个文件 1 单位
PowerPoint	`.ppt, .pptx`	幻灯片数
Excel	`.xls, .xlsx`	工作表数
图片	`.png, .jpg, .jpeg, .webp, .gif, .bmp, .tif, .tiff`	每个文件 1 单位
HTML	`.html, .htm`	每个文件 1 单位

上传按文件名后缀检查格式，不区分大小写。PDF、PPT、Excel 需要能读取页数或单位数；上传不通过 MIME 校验实际内容。空文件、不支持的后缀、加密或不可读的 PDF、超限文件会拒绝。HTML 为静态解析，不执行 JavaScript。1 MiB = 1,048,576 字节。

任务状态

queued、running 时继续查询；completed 时读取下载地址；failed 时读取 error 并停止查询；expired 表示结果保留期已结束。status 表示任务整体状态，API 的最终 ZIP 就绪后才是 completed。

task.status	含义与规则
`queued`	已接收，等待处理或获取 URL 原文件。
`running`	正在处理；解析、保存结果和 API 打包期间都使用此状态。
`completed`	最终结果已就绪，可查询并下载。
`failed`	处理失败，具体原因见 error；不要自动重新创建。
`expired`	结果已过保留期，根据 expires_at 判断；不再提供下载地址。

结果 ZIP 与下载

API 最终提供一个 ZIP，默认包含 Markdown、中间 JSON、结构化 JSON 和已保存的图片。extra_formats 只支持 html、docx、latex，选定文件加入同一 ZIP。API 任务不需要另建网页导出任务。未选额外格式时 results.full_zip_url 指向 base.zip，选择后指向 exports/ 下的 ZIP 文件。

化学任务返回 results.original_url 和 results.json_url，不生成 ZIP，不提供其他格式导出。

化学结果为 JSON 数组，每个分子保留 MolParser 全部原生字段；未检测到分子时返回 []。

molecular_structures.json

source, input_index, page_index, bbox, confidence, raw_caption, caption, smi, esmi, cxsmiles, markush, sru, groups

ZIP

result.zip
├── markdown.md
├── middle_json.json
├── structured_content.json
├── images/
│   └── …
├── model_output.json       (optional)
├── result.html             (extra_formats: html)
├── result.docx             (extra_formats: docx)
└── result.tex              (extra_formats: latex)

结果保留 7 天。results.full_zip_url 最长有效 15 分钟，不超过保留期。直接 GET 下载，不携带 Authorization。签名过期但文件未到期时，重新查询详情取得新地址。预览图片链接最长 2 小时，其他文件最长 15 分钟。

ZIP 内文档保留原生相对图片路径，并包含已保存的图片，不依赖 CDN 签名。请完整解压并保留目录结构。HTML 输入引用的远程图片不会自动归档，可能仍指向原网站。

错误码与处理

code 为 0 表示成功；非零 code 表示错误类别，msg 给出具体原因。查询失败或过期的任务仍返回 HTTP 200，但 code 分别为 task_failed、result_expired，results 为空字典。

HTTP 402

{
  "code": "quota_exceeded",
  "data": null,
  "msg": "not enough available pages/units"
}

HTTP	code	含义与规则
200	`task_failed`	解析失败，msg 为具体原因。
200	`result_expired`	结果已过期。
400	`invalid_request`	请求参数或文件无效，具体原因见 msg。
400	`too_many_pages`	文档超过页数或计费单位上限。
401	`unauthorized`	API 鉴权失败。
402	`quota_exceeded`	可用额度不足。
403	`user_disabled`	账号已禁用。
403	`pro_required`	此功能需要有效的 Pro 会员。
404	`not_found`	任务不存在或无权访问。
413	`file_too_large`	文件超过当前会员的大小限制。
500	`internal_error`	服务端处理失败，具体原因见 msg。

PaddleOCR API 文档 - 文档解析接口（Markdown / JSON）

开始使用

概览

鉴权与请求头

完整调用示例

API 接口

创建任务

方式一：直传文件

请求体参数 · multipart/form-data

响应字段 · 200 OK

方式二：提交 URL

请求体参数 · application/json

响应字段 · 200 OK

获取任务列表

查询参数

响应字段 · 200 OK

TaskSummary

获取任务结果

路径参数

响应字段 · 200 OK

Task

File

results

参考说明

输入格式与限制

任务状态

结果 ZIP 与下载

错误码与处理