文档解析 API

欢迎使用文档解析 API！本文档将帮助您快速集成我们的文档解析服务。

快速开始

1. 获取 API 密钥

首先，您需要在用户中心创建一个 API 密钥：

登录到您的账户
进入 API 密钥管理页面
点击"创建新密钥"按钮
复制生成的密钥（密钥仅显示一次，请妥善保管）

2. 认证方式

所有 API 请求都需要在 HTTP 请求头中包含 Authorization 字段：

Authorization: Bearer YOUR_API_KEY

API 端点

基础 URL

生产环境: http://8.148.69.123:8088/api
测试环境: http://8.148.69.123:8088/api

单个文件解析

创建解析任务

创建一个新的文档解析任务。

端点: POST /api/v1/extract/task

接口说明：

适用于通过 API 创建解析任务的场景，用户须先申请 Token
单个文件大小不能超过 200MB，文件页数不超出 600 页
该接口不支持文件直接上传，需要提供可访问的文件 URL
header 头中需要包含 Authorization 字段，格式为 Bearer + 空格 + Token

请求参数:

参数	类型	是否必选	示例	描述
url	string	是	https://example.com/document.pdf	文件 URL，支持.pdf、.doc、.docx、.ppt、.pptx、.png、.jpg、.jpeg多种格式
isOcr	boolean	否	true	是否启动 OCR 功能，默认 false
enableFormula	boolean	否	true	是否开启公式识别，默认 true
enableTable	boolean	否	true	是否开启表格识别，默认 true
language	string	否	ch	指定文档语言，默认 ch
dataId	string	否	doc_123	解析对象对应的数据 ID。由大小写英文字母、数字、下划线（_）、短划线（-）、英文句号（.）组成，不超过 128 个字符
callback	string	否	http://127.0.0.1/callback	解析结果回调通知您的 URL，支持使用 HTTP 和 HTTPS 协议的地址
seed	string	否	random_seed_123	随机字符串，用于回调通知请求中的签名。由英文字母、数字、下划线（_）组成，不超过 64 个字符。当使用 callback 时，该字段必须提供
extraFormats	array[string]	否	["docx","html"]	额外导出格式，支持 docx、html、latex 三种格式中的一个或多个
pageRanges	string	否	1-600	指定页码范围，格式为逗号分隔的字符串。例如："2,4-6"：表示选取第2页、第4页至第6页；"2--2"：表示从第2页一直选取到倒数第二页
modelVersion	string	否	pipeline	模型版本，两个选项：pipeline、vlm，默认 pipeline

Python 请求示例:

import requests

token = "您的 API Token"
url = "http://8.148.69.123:8088/api/v1/extract/task"
header = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}
data = {
    "url": "https://example.com/document.pdf",
    "isOcr": True,
    "enableFormula": True,
    "enableTable": True,
    "language": "ch"
}

res = requests.post(url, headers=header, json=data)
print(res.status_code)
print(res.json())

CURL 请求示例:

curl --location --request POST 'http://8.148.69.123:8088/api/v1/extract/task' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "url": "https://example.com/document.pdf",
    "isOcr": true,
    "enableFormula": true,
    "enableTable": true,
    "language": "ch"
}'

响应参数说明:

参数	类型	示例	说明
code	int	0	接口状态码，成功：0
message	string	ok	接口处理信息
data.taskId	string	a90e6ab6-44f3-4554-b459-b62fe4c6b436	提取任务 id，可用于查询任务结果
timestamp	long	1640995200000	时间戳

响应示例:

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "a90e6ab6-44f3-4554-b459-b62fe4c6b436"
  },
  "timestamp": 1640995200000
}

获取任务结果

查询解析任务的进度和结果。

端点: GET /api/v1/extract/task/{taskId}

接口说明：

通过 taskId 查询提取任务目前的进度
任务处理完成后，接口会响应对应的提取详情
header 头中需要包含 Authorization 字段，格式为 Bearer + 空格 + Token

Python 请求示例:

import requests

token = "您的 API Token"
task_id = "a90e6ab6-44f3-4554-b459-b62fe4c6b436"
url = f"http://8.148.69.123:8088/api/v1/extract/task/{task_id}"
header = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}

res = requests.get(url, headers=header)
print(res.status_code)
print(res.json())
print(res.json()["data"])

CURL 请求示例:

curl --location --request GET 'http://8.148.69.123:8088/api/v1/extract/task/{taskId}' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Accept: */*'

响应参数说明:

参数	类型	示例	说明
code	int	0	接口状态码，成功：0
message	string	ok	接口处理信息
data.taskId	string	abc**	任务 ID
data.state	string	done	任务处理状态，完成:done，pending: 排队中，running: 正在解析，failed：解析失败，converting：格式转换中
data.fullZipUrl	string	https://cdn.parse4ai.com/xxx.zip	文件解析结果压缩包
data.markdownUrl	string	https://cdn.parse4ai.com/xxx.md	Markdown 文件 URL
data.errMsg	string	文件格式不支持	解析失败原因，当 state=failed 时有效
timestamp	long	1640995200000	时间戳

响应示例（进行中）:

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "47726b6e-46ca-4bb9-******",
    "state": "running",
    "errMsg": ""
  },
  "timestamp": 1640995200000
}

响应示例（完成）:

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "47726b6e-46ca-4bb9-******",
    "state": "done",
    "fullZipUrl": "https://cdn.parse4ai.com/pdf/018e53ad-d4f1-475d-b380-36bf24db9914.zip",
    "markdownUrl": "https://cdn.parse4ai.com/pdf/018e53ad-d4f1-475d-b380-36bf24db9914.md",
    "errMsg": ""
  },
  "timestamp": 1640995200000
}

响应示例（失败）:

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "47726b6e-46ca-4bb9-******",
    "state": "failed",
    "errMsg": "文件格式不支持，请上传符合要求的文件类型"
  },
  "timestamp": 1640995200000
}

批量文件解析

URL 批量解析

适用于通过 API 批量创建提取任务的场景。

端点：POST http://8.148.69.123:8088/api/v1/extract/task/batch

接口说明：

单次请求最多 200 个文件
单个文件大小≤200MB、页数≤600
header 中需要携带 Authorization: Bearer <Token>

Python 请求示例：

import requests

token = "官网申请的api token"
url = "http://8.148.69.123:8088/api/v1/extract/task/batch"
header = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}
data = {
    "files": [
        {"url":"https://example.com/document.pdf", "data_id": "abcd"}
    ],
    "model_version": "vlm"
}
response = requests.post(url, headers=header, json=data)
print(response.status_code)
print(response.json())

CURL 请求示例：

curl --location --request POST 'http://8.148.69.123:8088/api/v1/extract/task/batch' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: */*' \
--data-raw '{
    "files": [
        {"url":"https://example.com/document.pdf", "data_id": "abcd"}
    ],
    "model_version": "vlm"
}'

请求体参数说明：

参数	类型	是否必选	示例	描述
files[].url	string	是	https://.../demo.pdf	文件链接，支持 pdf/doc/docx/ppt/pptx/png/jpg/jpeg
files[].is_ocr	bool	否	true	是否启动 ocr 功能，默认 false，仅对 pipeline 模型有效
files[].data_id	string	否	abc**	业务数据 ID，≤128 个字符
files[].page_ranges	string	否	1-600	指定页码范围，例如 `2,4-6`、`2--2`
enable_formula	bool	否	true	是否开启公式识别，默认 true，仅对 pipeline 模型有效
enable_table	bool	否	true	是否开启表格识别，默认 true，仅对 pipeline 模型有效
language	string	否	ch	文档语言，仅对 pipeline 模型有效
callback	string	否	https://example.com/callback	结果回调地址（POST + JSON），为空则需轮询
seed	string	否	abc**	回调签名使用的随机字符串，使用 callback 时必填
extra_formats	[string]	否	["docx","html"]	额外导出格式，支持 docx/html/latex
model_version	string	否	vlm	模型版本，`pipeline`（默认）或 `vlm`

响应参数说明：

参数	类型	示例	说明
code	int	0	接口状态码，0 表示成功
msg	string	ok	接口处理信息
trace_id	string	c876cd60b202f2396de1f9e39a1b0172	请求 ID
data.batch_id	string	2bb2f0ec-a336-4a0a-b61a-****	批量任务 ID，可用于查询结果

{
  "code": 0,
  "data": {
    "batch_id": "2bb2f0ec-a336-4a0a-b61a-241afaf9cc87"
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}

批量获取任务结果

通过 batch_id 查询批量任务的整体进度与结果。

端点：GET http://8.148.69.123:8088/api/v1/extract-results/batch/{batch_id}

Python 请求示例：

import requests

token = "官网申请的api token"
batch_id = "2bb2f0ec-a336-4a0a-b61a-241afaf9cc87"
url = f"http://8.148.69.123:8088/api/v1/extract-results/batch/{batch_id}"
header = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}
res = requests.get(url, headers=header)
print(res.status_code)
print(res.json())
print(res.json()["data"])

CURL 请求示例：

curl --location --request GET 'http://8.148.69.123:8088/api/v1/extract-results/batch/{batch_id}' \
--header 'Authorization: Bearer *****' \
--header 'Accept: */*'

响应参数说明：

参数	类型	示例	说明
code	int	0	接口状态码
msg	string	ok	接口处理信息
trace_id	string	c876cd60b202f2396de1f9e39a1b0172	请求 ID
data.batch_id	string	2bb2f0ec-a336-4a0a-b61a-241afaf9cc87	批次 ID
data.extract_result[].file_name	string	demo.pdf	文件名
data.extract_result[].state	string	done	任务状态：done、pending、running、failed、converting
data.extract_result[].full_zip_url	string	https://cdn-mineru...zip	文件解析结果压缩包 URL（完成时）
data.extract_result[].err_msg	string	...	失败原因（state=failed 时）
data.extract_result[].data_id	string	abc**	业务数据 ID
data.extract_result[].extract_progress.*	object		解析进度字段，state=running 时有效

{
  "code": 0,
  "data": {
    "batch_id": "2bb2f0ec-a336-4a0a-b61a-241afaf9cc87",
    "extract_result": [
      {
        "file_name": "example.pdf",
        "state": "done",
        "err_msg": "",
        "full_zip_url": "https://cdn-mineru.openxlab.org.cn/pdf/018e53ad-d4f1-475d-b380-36bf24db9914.zip"
      },
      {
        "file_name":"demo.pdf",
        "state": "running",
        "err_msg": "",
        "extract_progress": {
          "extracted_pages": 1,
          "total_pages": 2,
          "start_time": "2025-01-20 11:43:20"
        }
      }
    ]
  },
  "msg": "ok",
  "trace_id": "c876cd60b202f2396de1f9e39a1b0172"
}

任务状态

状态	说明
pending	排队中
running	正在解析
done	解析完成
failed	解析失败
converting	格式转换中

常见错误码

错误码	说明	解决建议
-20002	Token 错误	检查 Token 是否正确，请检查是否有 Bearer 前缀或更换新 Token
-20011	Token 过期	更换新 Token
-500	传参错误	请确保参数类型及 Content-Type 正确
-10001	服务异常	请稍后再试
-10002	请求参数错误	检查请求参数格式
-60002	获取匹配的文件格式失败	检测文件类型失败，请求的文件名及链接中带有正确的后缀名
-60003	文件读取失败	请检查文件是否损坏并重新上传
-60004	空文件	请上传有效文件
-60005	文件大小超出限制	检查文件大小，最大支持 200MB
-60006	文件页数超过限制	请拆分文件后重试
-60007	模型服务暂时不可用	请稍后重试或联系技术支持
-60008	文件读取超时	检查 URL 可访问
-60009	任务提交队列已满	请稍后再试
-60010	解析失败	请稍后再试
-60012	找不到任务	请确保 taskId 有效且未删除
-60013	没有权限访问该任务	只能访问自己提交的任务
-60015	文件转换失败	可以手动转为 PDF 再上传
-60017	页码余额不足	请充值或升级套餐

限制说明

单个文件大小：最大 200MB
文件页数：最大 600 页
支持的文件格式：PDF (.pdf)、Word (.doc, .docx)、PowerPoint (.ppt, .pptx)、图片 (.png, .jpg, .jpeg)

目录