文档解析
接口描述
【活动】新客专享福利,文档解析、文档解析(PaddleOCR-VL) 低至9元/千页
文档解析支持对doc、pdf、图片、xlsx等20多种格式文档进行解析,输出文档的版面、表格、阅读顺序、标题层级、旋转角度等信息,支持中、英、日、韩、法等20余种语言类型,可返回JSON与Markdown格式内容,将非结构化数据转化为易于处理的结构化数据。如希望快速可视化体验效果,可登录智能文档分析平台,一键上传文档,在线测试;在线工具和API服务的额度共享互通。
文档解析API服务为异步接口,需要先调用提交请求接口获取 task_id,然后调用获取结果接口进行结果轮询,建议提交请求后 5~10 秒轮询。提交请求接口QPS为2,获取结果接口QPS为10。
在线调试
您可以在 示例代码中心 中调试该接口,可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。
为方便您更好地使用文档解析服务,我们设立了专属交流群。您可通过下方二维码入群:

提交请求接口
请求说明
请求示例
HTTP 方法:POST
请求URL: https://aip.baidubce.com/rest/2.0/brain/online/v2/parser/task
URL参数:
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token,参考“Access Token获取” |
Header如下:
| 参数 | 值 |
|---|---|
| Content-Type | application/x-www-form-urlencoded |
Body中放置请求参数,参数详情如下:
请求参数
| 参数 | 是否必选 | 类型 | 可选值范围 | 说明 |
|---|---|---|---|---|
| file_data | 和file_url二选一 | string | - | 文件的base64编码数据:-版式文档:pdf、ofd、ppt、pptx-流式文档:doc、docx、txt、xls、xlsx、wps、html、mhtml、ods、tsv、rtf、odt、odp-图片文档:jpg、jpeg、png、bmp、tif、tiff、webp、gif、ico、svg,图片最长边不大于8192px图片不超过10M,流式文档大小不超过50M若文档大小超过50M,须从file_url方式上传。优先级: file_data > file_url,当file_data字段存在时,file_url字段失效 |
| file_url | 和file_data二选一 | string | - | 文件数据URL,URL长度不超过1024字节,支持单个URL传入。PDF文档大小不超过300M,非PDF文档大小不超过50M,其中PDF文档最大支持2000页优先级: file_data > file_url,当file_data字段存在时,file_url字段失效请注意关闭URL防盗链 |
| file_name | 是 | string | - | 文件名,请保证文件名后缀正确,例如 申请书.pdf |
| recognize_formula | 否 | bool | True/False | 是否对版式类型文档进行公式识别 |
| analysis_chart | 否 | bool | True/False | 是否对统计图表进行解析 |
| angle_adjust | 否 | bool | True/False | 是否对图片进行角度矫正 |
| parse_image_layout | 否 | bool | True/False | 是否返回文档中图片的版面信息 |
| language_type | 否 | string | - | 识别语种类型,默认为 CHN_ENG,可选值如下:-CHN_ENG:中英文 - JAP:日语- KOR:韩语- FRE:法语- SPA:西班牙语- POR:葡萄牙语- GER:德语- ITA:意大利语- RUS:俄语- DAN:丹麦语- DUT:荷兰语- MAL:马来语- SWE:瑞典语- IND:印尼语- POL:波兰语- ROM:罗马尼亚语- TUR:土耳其语- GRE:希腊语- HUN:匈牙利语- THA:泰语- VIE:越南语- ARA:阿拉伯语- HIN:印地语 |
| switch_digital_width | 否 | string | - | 是否对数字进行全半角转换,默认为 auto,可选值如下:-auto:不转换,按模型识别结果输出 - half:将所有的符号转换为半角输出- full:将所有的符号转换为全角输出 |
| html_table_format | 否 | bool | True/False | 是否将识别出的表格转换为 HTML 格式返回,default=False |
| return_doc_chunks | 否 | dict | - | 是否返回文档切分后的片段数据(如按语义、字数、标点)。如有需要,可按下方说明进行传参 |
| + switch | 否 | bool | True/False | 是否进行文档内容切分,default=True |
| + split_type | 否 | str | - | 切分方式,目前支持两种,default=chunk - chunk:按照「chunk_size」来切 - mark:按照「separators」来切 |
| + separators | 否 | list |
- | 切分标点,default=['。', ';', '!', '?', ';', '!', '?'],split_type=mark时生效 |
| + chunk_size | 否 | int | - | 切分块的大小,chunk_size=-1时,表示按照语义自动切分,不限定块的大小;chunk_size>0时,表示按照字符长度切 |
| page_filter | 否 | list | - | 指定页码进行解析,默认解析全部页数。页码从0开始,[1, 3] 表示第 2、4 页 。流式文档不支持,流式文件需先转换为版式文件。 |
| need_pdffile_data | 否 | bool | True/False | 查询成功时额外返回整份PDF文件。default=False |
| detect_seal | 否 | bool | True/False | 是否检测印章。default=True |
| recognize_seal | 否 | bool | True/False | 是否识别章面文字;开启后自动打开detect_seal。default=True |
| erase_seal | 否 | bool | True/False | 擦除印章。优先级高于章面识别;与 recognize_seal 同时开时保留检测框、去掉文字。建议不要和章面识别同时开。default=False 印章参数组合说明: detect_seal=false、recognize_seal=false、erase_seal=false → 不做印章 detect_seal=true、recognize_seal=false、erase_seal=false → 只有检测框 recognize_seal=true、erase_seal=false → 检测 + 章面文字(自动打开检测) erase_seal=true → 擦除章面;若同时识别,框还在、文字去掉 |
| erase_watermark | 否 | bool | True/False | 是否去除水印 default=False |
| parse_image_valid_ratio | 否 | float | - | 图片占页面面积的过滤阈值,低于阈值的区域可能不写入images。default=0.1 |
| word2pdf | 否 | bool | True/False | 将Word转成PDF再按版式解析。default=False |
| traditional2simplified | 否 | bool | True/False | 是否繁体转简体。default=False |
| need_pdffile_vis_data | 否 | bool | True/False | 当开启印章擦除等预处理能力后,是否输出处理后的PDF default=False |
| need_inner_image_data | 否 | bool | True/False | 返回文档里的内嵌图片数据default=False |
请求代码示例
提示:使用示例代码前,请记得替换其中的示例Token、文档地址或Base64信息。
1import requests
2import os
3import base64
4
5
6def create_task(url, file_path, file_url):
7 """
8 Args:
9 url: string, 服务请求链接
10 file_path: 本地文件路径
11 file_url: 文件链接
12 Returns: 响应
13 """
14 # 文件请求
15 with open(file_path, "rb") as f:
16 file_data = base64.b64encode(f.read())
17 data = {
18 "file_data": file_data, #与file_url二选一,只传 URL 时不要带 file_data
19 "file_url": file_url,
20 "file_name": os.path.basename(file_path)
21 }
22
23 # 文档切分参数,非必传
24 # return_doc_chunks = json.dumps({"switch": True, "chunk_size": -1})
25 # data["return_doc_chunks"] = return_doc_chunks
26
27 headers = {'Content-Type': 'application/x-www-form-urlencoded'}
28
29 response = requests.post(url, headers=headers, data=data)
30 return response
31
32if __name__ == '__main__':
33 request_host = "https://aip.baidubce.com/rest/2.0/brain/online/v2/parser/task?" \
34 "access_token={token}"
35 file_path = "./test.pdf"
36 response = create_task(request_host, file_path, "")
37 print(response.json())
返回说明
返回参数
| 字段 | 类型 | 说明 |
|---|---|---|
| log_id | uint64 | 唯一的log id,用于问题定位 |
| error_code | int | 错误码 |
| error_msg | string | 错误描述信息 |
| result | dict | 返回的结果列表 |
| + task_id | string | 该请求生成的task_id,后续使用该task_id获取解析结果 |
返回示例
成功返回示例:
1{
2 "error_code": 0,
3 "error_msg": "",
4 "log_id": "10138598131137362685273505665433",
5 "result": {
6 "task_id": "task-3zy9Bg8CHt1M4pPOcX2q5bg28j26801S"
7 }
8}
失败返回示例(详细的错误码说明见API文档-错误码):
1{
2 "error_code": 282003,
3 "error_msg": "missing parameters",
4 "log_id": "37507631033585544507983253924141",
5 "result": "null"
6}
获取结果接口
在线调试
您可以在 示例代码中心 中调试该接口,可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。
请求说明
请求示例
HTTP 方法:POST
请求URL: https://aip.baidubce.com/rest/2.0/brain/online/v2/parser/task/query
URL参数:
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token,参考“Access Token获取” |
Header如下:
| 参数 | 值 |
|---|---|
| Content-Type | application/x-www-form-urlencoded |
Body中放置请求参数,参数详情如下:
请求参数
| 参数 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
| task_id | 是 | string | 发送提交请求时返回的task_id |
请求代码示例
提示:使用示例代码前,请记得替换其中的示例Token、task_id。
1import requests
2
3def query_task(url, task_id):
4 """
5 Args:
6 url: string, 请求链接
7 task_id: string, task id
8 Returns: 响应
9 """
10 data = {
11 "task_id": task_id
12 }
13 headers = {'Content-Type': 'application/x-www-form-urlencoded'}
14 print(url)
15 response = requests.post(url, headers=headers, data=data)
16 return response
17
18
19if __name__ == '__main__':
20 # 需要替换为实际的任务id
21 task_id = "task_id"
22 # {access_token} 需要替换为实际调用鉴权接口获取的access_token
23 request_host = "https://aip.baidubce.com/rest/2.0/brain/online/v2/parser/task/query?access_token={access_token}"
24 resp = query_task(request_host, task_id)
25 print(resp.json())
返回说明
返回参数
| 字段 | 类型 | 说明 |
|---|---|---|
| log_id | uint64 | 唯一的log id,用于问题定位 |
| error_code | int | 错误码 |
| error_msg | string | 错误描述信息 |
| result | dict | 返回的结果列表 |
| + task_id | string | 任务ID |
| + status | string | 任务状态,pending:排队中;running:运行中;success:成功;failed:失败 |
| + task_error | string | 解析报错信息,包含任务失败、额度不够 |
| + markdown_url | string | 文档解析结果的markdown格式链接,链接有效期30天 |
| + parse_result_url | string | 文档解析结果的Json链接,链接有效期30天 |
| + pdf_file_url | string | 整份 PDF,仅 need_pdffile_data=true 且 success 时下发,有效期 30 天。未开启时没有该字段 |
| + cost_page_num | int | 任务解析页数,即该任务对应的消耗额度 |
返回示例 成功返回示例:
1{
2 "error_code": 0,
3 "error_msg": "success",
4 "log_id": "23082741357017441497115454226056",
5 "result": {
6 "task_id": "task-example",
7 "status": "success",
8 "task_error": null,
9 "parse_result_url": "https://example.invalid/result.json",
10 "markdown_url": "https://example.invalid/result.md",
11 "cost_page_num": 5
12 }
13}
可通过parse_result_url下载解析结果的JSON文件,parse_result_url的返回参数如下:
| 字段 | 类型 | 说明 |
|---|---|---|
| file_name | string | 文档名称 |
| file_id | string | 文档ID |
| pdf_data | string | need_pdffile_data=true 时返回的PDF文件下载地址,,链接有效期30天 |
| pdf_vis_data | string | need_pdffile_vis_data=true` 时返回的预处理后的PDF下载地址,链接有效期30天 |
| pages | list | 文件页面解析内容 |
| + page_id | string | 页码ID |
| + page_num | int | 页码数,从0开始 |
| + page_angle | int | 页面旋转角度 |
| + text | string | 当前页文本内容,可能包含公式标记、表格 HTML 等 |
| + layouts | list | 页面内容版式分析的结果 |
| ++ layout_id | string | layout ID,layout元素唯一标志,以"xxxxx-layout-{global_layout_index}"形式,global_layout_index为layout元素整个文档的全局索引 |
| ++ text | string | layout对应的文本内容。 |
| ++ position | list | layout版面元素在页面中的位置,[x, y, w, h] box框 |
| ++ type | string | layout版面元素类型,当前可取值: • text:文本 • table:表格 • head_tail:页眉页脚页码等辅助区域 • footer:页脚 • number:页码 • image:文档中的插图 • contents:目录 • seal:印章 • title:标题 • formula:公式 • head_sign:手写签名 • footnote:脚注 |
| ++ sub_type | string | layout元素子类型,当type为table、title、image、headtail时,subtype有值。 table类的 subtype 包含: • wired_table:有线表格 • wireless_table:无线表格 title类的 subtype 包含: • title{n},代表n级标题,比如title2代表二级标题 • image_title:图标题 • table_title:表标题 image类的 subtype 包含: • chart:统计图表 • figure:普通插图 • QR_code:二维码 • Bar_code:条形码 head_tail类的 subtype 包含: • header:页眉 • footer:页脚 • number:页码 |
| ++ score | number | 版面检测得分,不等于识别准确率 |
| ++ parent | string | 标题层级树中父节点的layout ID,若当前layout为一级标题,其parent为 "root"。在table和image的内嵌版面信息中暂时都为空 |
| ++ children | list | 标题层级树中子节点的layout ID。在table和image的内嵌版面信息中暂时都为空 |
| + tables | list | 页面表格解析结果 |
| ++ layout_id | string | 对应表格等layout ID,与layouts中的元素type为table的元素的layout ID对应 |
| ++ markdown | string | 表格内容的markdown形式 |
| ++ table_html | string | 表格 HTML,html_table_format=true时有值 |
| ++ table_title_id | list | 表格标题对应的layout_id,默认为null |
| ++ position | list | 边框数据 「x, y, w, h」(x, y)为坐标点坐标,w为box宽度,h为box高度(以页面坐标为原点),版式格式时有效 |
| ++ cells | list | 单元格的内嵌版面信息,layout类型为表格时有值 |
| +++ layout_id | string | 单元格layout ID |
| +++ text | string | 单元格内容 |
| +++ position | array/null | 单元格位置 |
| +++ type | string | 单元格内容类型 |
| +++ sub_type | string | 单元格内容子类型 |
| ++ matrix | list | 二维数组,表示表格内布局位置信息,每个元素对应cells列表中元素的索引 |
| ++ merge_table | string | 默认开启,「begin」- 跨页表格开始、「inner」- 跨页表格中间表格(表格跨页超过两页)、「end」- 跨页表格结束;非跨页表格该字段为空 |
| + images | list | 页面中图片解析结果 |
| ++ layout_id | string | 对应图片等layout ID,与layouts中的元素type为image的元素的layout ID对应 |
| ++ image_title_id | list | 图片标题对应的layout_id,默认为null |
| ++ position | list | 图片的位置数据 「x, y, w, h」(x, y)为坐标点坐标,w为box宽度,h为box高度(以页面坐标为原点),版式格式时有效 |
| ++ content_layouts | list | 图片的内嵌版面信息 |
| ++ data_url | string | 图片存储链接,有效期 30 天 |
| ++ image_description | string | 对统计图表进行内容解析和描述,输出结果为json字符串,可通过json.loads结构化为json格式 |
| + seals | list | 页面印章识别结果 |
| ++ layout_id | string | 印章唯一标志,格式如 "seal-1" |
| ++ position | list | 印章位置 [x, y, w, h] |
| ++ score | number | 印章识别置信度分数 |
| ++ major_str | string | 印章主体文字内容 |
| ++ minor_strs | list | 印章次要文字内容列表(如多行环绕文字) |
| ++ image | string | 印章图片链接 |
| + meta | dict | 页面元信息 |
| ++ page_width | int | 页面宽度 |
| ++ page_height | int | 页面高度 |
| ++ is_scan | bool | 是否扫描件 |
| ++ page_angle | number | 页面角度 |
| ++ page_type | string | 页面属性,包括:「text」-正文、「contents」-目录、「appendix」-附录、「doc」-含有文档插图、「seal」-签章页、「others」-其他 |
| ++ sheet_name | string | excel的sheet名 |
| chunks | list | 文件内容切分结果,return_doc_chunks中switch为True时有值 |
| + chunk_id | string | 切片的ID |
| +content | string | 切片的内容 |
| + type | string | 切片类型,为text或者table |
| + meta | dict | chunk元信息 |
| ++ title | list | chunk所属的多级标题内容 |
| ++ position | list | chunk的位置,根据分块算法有可能chunk跨多个页 |
| ++ box | list | chunk的位置坐标 |
| ++ page_num | int | chunk内容所在页数 |
表格结构示例
以下为合并单元格索引规则示意。cells 共 5 项,合法索引是 0~4,首行索引 0 重复表示跨两列。
1{
2 "cells": [
3 {"text": "合并表头"},
4 {"text": "备注"},
5 {"text": "A"},
6 {"text": "B"},
7 {"text": "C"}
8 ],
9 "matrix": [[0, 0, 1], [2, 3, 4]]
10}
页面结果示例
以下为页面结果片段,用于说明字段结构;实际返回可能包含更多版面块和字段。
1{
2 "file_name": "standard-layout-synthetic-fixture.pdf",
3 "file_id": "file-example",
4 "pages": [
5 {
6 "page_id": "page-example",
7 "page_num": 0,
8 "page_angle": 0,
9 "layouts": [
10 {
11 "layout_id": "header-example",
12 "text": "文档页眉",
13 "position": [62, 31, 112, 8],
14 "type": "head_tail",
15 "sub_type": "header"
16 },
17 {
18 "layout_id": "title-example",
19 "text": "文档标题",
20 "position": [110, 78, 375, 22],
21 "type": "title",
22 "sub_type": "title_1"
23 }
24 ],
25 "meta": {
26 "page_width": 595,
27 "page_height": 841,
28 "is_scan": false,
29 "page_type": "doc"
30 }
31 }
32 ]
33}
常见错误码
HTTP 请求成功、业务请求成功和异步任务成功是不同状态。以下保留常见错误码,完整说明以错误码文档为准。
| error_code | error_msg | 含义 |
|---|---|---|
| 0 | success | 业务请求成功,解析状态需再检查 result.status。 |
| 216200 | empty file or file url | 文件内容或文件 URL 为空。 |
| 216201 | file format error | 文件后缀或格式不符合要求。 |
| 216202 | file size error | 文件大小超限,具体限制见返回信息。 |
| 282000 | internal error | 服务内部异常。 |
| 282003 | missing parameters | 参数缺失或非法;使用范围字符串指定页也可能返回此错误。 |
| 282005 | quota exceed error | 额度不足。 |
| 282006 | check user auth error | 鉴权校验失败。 |
| 282007 | task not exist, please check task id | 任务不存在或任务 ID 非法。 |
| 282111 | url format illegal | 文件 URL 非法。 |
| 282112 | url download timeout | 文件下载超时。 |
| 282114 | url size error | 文件 URL 过长。 |
| 282115 | query task failed | 查询任务失败。 |
| 282116 | create task failed | 创建任务失败。 |
| 282117 | auth service failed | 鉴权服务异常。 |
| 282118 | auth concurrency limit reached | 并发限制。 |
| 282119 | return doc chunk param format error | 切分参数格式非法。 |
| 282120 | file base64 format error | 文件 Base64 格式错误。 |
| 282121 | request param content length too large | 请求体过大。 |
| 282122 | request param content length too large, please using file url to request | 请求体过大,需使用文件 URL。 |
评价此篇文章
