API文档
更新时间：2025-04-28
申请试用
该接口正在邀测中，请您先提交 合作咨询 或 提交工单，提供公司名称、appid、应用场景等信息，工作人员协助开通权限后方可使用。
接口描述
iOCR 全场景识别采用 MoE 混合专家架构，无需分类调用、无需定制训练，一个接口实现全场景结构化识别。基于意图识别模型，自动将同一任务中的不同类型文件分发至对应专家模型，已预置 10 余种 OCR 识别模型与通用抽取大模型，同时支持自定义文档抽取模型，不限类型与版式，轻松提取复杂文档关键字段。
登录 iOCR 全场景识别平台，可在示例项目空间快速体验，也可创建您专属的项目空间与抽取模型，平台和接口服务的额度共享互通。
本服务为异步接口，包含提交请求、获取结果两个子接口，详情如下：
- iOCR 全场景识别-提交请求：传入图片/PDF、项目空间ID等参数，创建识别任务并获取任务ID，该接口支持2QPS；
- iOCR 全场景识别-获取结果：成功创建任务后，传入任务ID获取识别结果，该接口支持10QPS。可调用获取结果接口进行结果轮询，建议提交请求后30秒开始轮询。
iOCR 全场景识别-提交请求
请求说明
请求示例
HTTP 方法：POST
请求URL： https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise/universal/request
URL参数：
| 参数 | 值 |
|---|---|
| access_token | 通过API Key和Secret Key获取的access_token,参考“Access Token获取” |
Header如下：
| 参数 | 值 |
|---|---|
| Content-Type | application/x-www-form-urlencoded |
Body中放置请求参数，参数详情如下：
请求参数
| 参数 | 是否必选 | 类型 | 可选值范围 | 说明 |
|---|---|---|---|---|
| file_name | 是 | string | - | 文件名称，例如：通过pdf_file传入一份名为test的文件，该字段需传入test.pdf。注意： 文件名称后缀需与文件实际类型一致 |
| image | 和url/pdf_file/ofd_file四选一 | string | - | 图像数据，base64编码后进行urlencode，要求base64编码和urlencode后大小不超过10M，最短边至少15px，最长边最大8192px，支持jpg/jpeg/png/bmp格式优先级： image>url>pdf_file>ofd_file，当image字段存在时，url、pdf_file、ofd_file字段失效 |
| url | 和image/pdf_file/ofd_file 四选一 | string | - | 图片完整URL，URL长度不超过1024字节，URL对应的图片要求base64编码和urlencode后大小不超过10M，最短边至少15px，最长边最大8192px优先级： image>url>pdf_file>ofd_file，当image字段存在时，url字段失效 注意： 请关闭URL防盗链 |
| pdf_file | 和image/url/ofd_file四选一 | string | - | PDF文件，base64编码后进行urlencode，要求base64编码和urlencode后大小不超过10M，最短边至少15px，最长边最大8192px。若PDF存在多页，默认识别全部页优先级： image>url>pdf_file>ofd_file，当image、url字段存在时，pdf_file字段失效 |
| ofd_file | 和image/url/pdf_file四选一 | string | - | OFD文件，base64编码后进行urlencode，要求base64编码和urlencode后大小不超过10M，最短边至少15px，最长边最大8192px。若OFD存在多页，默认识别全部页优先级： image>url>pdf_file>ofd_file，当image、url、pdf_file字段存在时，ofd_file字段失效 |
| templateSign | 和 classifierId 二选一 | string | - | 文件类型 ID，自定义模型或预置模型的唯一标示，可用于调用指定的识别模型进行结构化识别。自定义模型 ID： 可在「模型管理」页查看并复制使用预置模型 ID： 可在「预置模型清单」查看并复制使用 |
| classifierId | 和 templateSign 二选一 | string | - | 项目空间 ID，项目空间识别规则的唯一标示，可用于调用指定项目空间的识别规则，对传入的图片自动分类及识别，可在「项目空间」查看并复制使用。优先级： templateSign>classfierId，当templateSign字段存在时，classfierId字段失效 |
请求代码示例
提示一：使用示例代码前，请记得替换其中的示例Token、文件地址等信息
提示二：目前仅提供Python语言
Python
1import base64
2import requests
3import os
4'''
5iOCR 全场景识别-提交请求
6'''
7file_path = '[本地文件]'
8request_host = "https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise/universal/request"
9encoded_string = ''
10with open(file_path, 'rb') as file:
11 file_base64 = base64.b64encode(file.read()).decode('utf-8')
12# 优先级：templateSign>classifierId，当templateSign字段存在时，classifierId字段失效
13data = {
14 'image': file_base64,
15 'fileName': os.path.basename(file_path),
16 "classifierId":"project-yht3ia44fyixcwm2",
17 "templateSign":"id_card_font"
18
19}
20access_token = '[调用鉴权接口获取的token]'
21request_url = request_host + "?access_token=" + access_token
22headers = {'Content-Type': 'application/x-www-form-urlencoded'}
23response = requests.post(request_url, headers=headers, data=data)
24if response:
25 print(response.json())返回说明
返回参数
| 字段 | 类型 | 说明 |
|---|---|---|
| log_id | string | 唯一的 log_id，用于问题定位 |
| error_code | int | 错误码 |
| error_msg | string | 错误码描述信息 |
| error_explain | string | 错误码详细中文描述 |
| result | dict | 返回的结果列表 |
| + task_id | string | 该请求生成的task_id，可使用该task_id获取识别结果 |
返回示例
成功返回示例
JSON
1{
2 "error_code": 0,
3 "error_msg": "",
4 "log_id": "3599798266",
5 "task_result": {
6 "task_id": "task-2m8g3dhqmrv9cxfe"
7 }
8}失败返回示例（错误码说明详见API文档-错误码）：
JSON
1{
2 "error_code": 283016,
3 "error_msg": "parameters value error",
4 "error_explain": "classifier_id和template_sign不能同时为空",
5 "log_id": "3599798268",
6 "data": null
7}iOCR 全场景识别-获取结果
请求说明
请求示例
HTTP 方法：POST
请求URL：https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise/universal/get_result
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信息
提示二：目前仅提供Python语言
Python
1import requests
2'''
3iOCR 全场景识别-获取结果
4'''
5
6request_host = "https://aip.baidubce.com/rest/2.0/solution/v1/iocr/recognise/universal/get_result"
7task_id = "task-xxxx"
8access_token = "[调用鉴权接口获取的token]"
9request_url = request_host + "?access_token=" + access_token
10data={
11 "task_id":"task-111"
12}
13headers = {'Content-Type': 'application/x-www-form-urlencoded'}
14response = requests.post(request_url, data=data, headers=headers)
15if response:
16 print(response.json())返回说明
返回参数
| 字段 | 类型 | 说明 |
|---|---|---|
| log_id | uint64 | 唯一的log id，用于问题定位 |
| error_code | int | 错误码 |
| error_msg | string | 错误描述信息 |
| task_result | dict | 任务详情列表 |
| + task_id | string | 任务id |
| + status | string | 任务状态，Success：成功；Running：处理中；Failed：失败 |
| + created | int | 创建时间，格式为：YYYY-MM-DD nn:nn:nn（UTC/GMT+08:00 东八区） |
| + started | int | 开始时间，格式为：YYYY-MM-DD nn:nn:nn（UTC/GMT+08:00 东八区） |
| + finished | int | 完成时间，格式为：YYYY-MM-DD nn:nn:nn（UTC/GMT+08:00 东八区） |
| + duration | int | 处理时长，单位为秒（s） |
| words_result_num | int | 识别结果数量，表示word_result结果数量 |
| words_result | list | 识别结果列表 |
| + doc_type | string | 文件类型 |
| + page_num | int | 页码信息，页码从1开始 |
| + doc_location | dict | 文件位置信息 |
| ++ box | [4][2]int | 四角点坐标框，[[x1,y1],[x2,y2],[,x3,y3],[x4,y4]]，分别对应坐标框四个点的坐标 |
| ++ cbox | array | 坐标框，「x, y, w, h」(x, y)为坐标点坐标，w为box宽度，h为box高度（以页面坐标为原点） |
| + kv_result | dict | 结构化识别结果，包含抽取字段和结果信息 |
| ++ single_key | dict | 单个字段抽取结果 |
| +++ {key} | []dict | 单个字段名称 |
| ++++ words | string | 单个字段抽取结果 |
| ++++ location | []dict | 抽取内容信息 |
| +++++ box | [4][2]int | 四角点坐标框，[[x1,y1],[x2,y2],[,x3,y3],[x4,y4]]，分别对应坐标框四个点的坐标 |
| +++++ cbox | [4]int | 坐标框，「x, y, w, h」(x, y)为坐标点坐标，w为box宽度，h为box高度（以页面坐标为原点） |
| ++ combo_key | dict | 组合字段抽取结果 |
| +++ {root_key} | []dict | 父字段名称 |
| ++++ {leaf_key} | []dict | 子字段名称 |
| +++++ words | string | 子字段抽取结果 |
| +++++ location | []dict | 抽取内容信息 |
| ++++++ box | [4][2]int | 四角点坐标框，[[x1,y1],[x2,y2],[,x3,y3],[x4,y4]]，分别对应坐标框四个点的坐标 |
| ++++++ cbox | [4]int | 坐标框，「x, y, w, h」(x, y)为坐标点坐标，w为box宽度，h为box高度（以页面坐标为原点） |
| ++ full_result | dict | 全文识别结果，仅在doc_type为"其他"，且识别规则兜底策略选择“全文识别”时返回 |
| ++ other_result | dict | 其他识别结果，如卡证质量、风险检测结果 |
返回示例
识别成功示例
JSON
1{
2 "error_code": 0,
3 "error_msg": "",
4 "log_id": "2761737701",
5 "task_result": {
6 "task_id": "task-2m8g3dhqmrv9cxfe",
7 "status": "Success",
8 "created": "2025-03-17 15:37:55",
9 "started": "2025-03-17 15:37:55",
10 "finished": "2025-03-17 15:38:02",
11 "duration": 7
12 },
13 "words_result_num": 1,
14 "words_result": [
15 {
16 "page_num": 1,
17 "doc_type": "其他",
18 "doc_location": null,
19 "kv_result": {
20 "single_key": {
21 "价税合计（大写）": [
22 {
23 "words": "叁佰陆拾圆整",
24 "location": {
25 "box": null,
26 "cbox": null
27 }
28 }
29 ],
30 "价税合计（小写）": [
31 {
32 "words": "￥360.00",
33 "location": {
34 "box": null,
35 "cbox": null
36 }
37 }
38 ],
39 "发票号码": [
40 {
41 "words": "3321192130",
42 "location": {
43 "box": null,
44 "cbox": null
45 }
46 },
47 {
48 "words": "No 07285251",
49 "location": {
50 "box": null,
51 "cbox": null
52 }
53 }
54 ],
55 "名称": [
56 {
57 "words": "百度在线网络技术（北京）有限公司",
58 "location": {
59 "box": null,
60 "cbox": null
61 }
62 },
63 {
64 "words": "阿里云计算有限公司",
65 "location": {
66 "box": null,
67 "cbox": null
68 }
69 }
70 ],
71 "地址、电话": [
72 {
73 "words": "北京市海淀区上地十街10号百度大厦三层",
74 "location": {
75 "box": null,
76 "cbox": null
77 }
78 },
79 {
80 "words": "杭州市转塘科技经济区块16号8幢 0571-85022088",
81 "location": {
82 "box": null,
83 "cbox": null
84 }
85 }
86 ],
87 "开户行及账号": [
88 {
89 "words": "招商银行北京分行大屯路支行866180100210002",
90 "location": {
91 "box": null,
92 "cbox": null
93 }
94 },
95 {
96 "words": "招商银行杭州高新支行502905023610702",
97 "location": {
98 "box": null,
99 "cbox": null
100 }
101 }
102 ],
103 "开票日期": [
104 {
105 "words": "2019年08月28日",
106 "location": {
107 "box": null,
108 "cbox": null
109 }
110 }
111 ],
112 "纳税人识别号": [
113 {
114 "words": "91110911717743469K",
115 "location": {
116 "box": null,
117 "cbox": null
118 }
119 },
120 {
121 "words": "91330106673959654P",
122 "location": {
123 "box": null,
124 "cbox": null
125 }
126 }
127 ]
128 },
129 "combo_key": {
130 "货物或应税劳务、服务信息": [
131 {
132 "单价": {
133 "words": "339. 62",
134 "location": {
135 "box": null,
136 "cbox": null
137 }
138 },
139 "单位": {
140 "words": "",
141 "location": {
142 "box": null,
143 "cbox": null
144 }
145 },
146 "数量": {
147 "words": "1",
148 "location": {
149 "box": null,
150 "cbox": null
151 }
152 },
153 "税率": {
154 "words": "",
155 "location": {
156 "box": null,
157 "cbox": null
158 }
159 },
160 "税额": {
161 "words": "20. 38",
162 "location": {
163 "box": null,
164 "cbox": null
165 }
166 },
167 "规格型号": {
168 "words": "",
169 "location": {
170 "box": null,
171 "cbox": null
172 }
173 },
174 "货物或应税劳务、服务名称": {
175 "words": "*信息技术服务*软件服务费",
176 "location": {
177 "box": null,
178 "cbox": null
179 }
180 },
181 "金额": {
182 "words": "339. 62",
183 "location": {
184 "box": null,
185 "cbox": null
186 }
187 }
188 }
189 ],
190 "购买方扣税凭证信息": [
191 {
192 "单价": {
193 "words": "2.30",
194 "location": {
195 "box": null,
196 "cbox": null
197 }
198 },
199 "合计": {
200 "words": "￥339.62",
201 "location": {
202 "box": null,
203 "cbox": null
204 }
205 },
206 "时间": {
207 "words": "18:50-17:06",
208 "location": {
209 "box": null,
210 "cbox": null
211 }
212 },
213 "油附加费": {
214 "words": "￥1.00",
215 "location": {
216 "box": null,
217 "cbox": null
218 }
219 },
220 "税额": {
221 "words": "Y20.38",
222 "location": {
223 "box": null,
224 "cbox": null
225 }
226 },
227 "证号": {
228 "words": "244926",
229 "location": {
230 "box": null,
231 "cbox": null
232 }
233 },
234 "车号": {
235 "words": "京B.26353",
236 "location": {
237 "box": null,
238 "cbox": null
239 }
240 },
241 "里程": {
242 "words": "6.0",
243 "location": {
244 "box": null,
245 "cbox": null
246 }
247 }
248 }
249 ]
250 }
251 }
252 }
253 ]
254}任务运行中示例：
JSON
1{
2 "error_code": 0,
3 "error_msg": "",
4 "log_id": "3739485273",
5 "task_result": {
6 "task_id": "task-q0zaegy82ujqe6qc",
7 "status": "Running",
8 "reason": "",
9 "created": "2025-03-17 17:29:38",
10 "started": "2025-03-17 17:29:38",
11 "finished": "",
12 "duration": 5
13 },
14 "words_result": null
15}预置模型清单
| 序号 | 文件类型 | 文件类型 ID（通过templateSign传入） | 默认请求参数 | 备注 |
|---|---|---|---|---|
| 1 | 身份证正面 | id_card_front | id_card_side = front detect_ps = true detect_risk = true detect_quality = true detect_photo = true detect_card = false detect_direction = true |
即人像面，返参含义详见 API文档-身份证识别 |
| 2 | 身份证反面 | id_card_back | id_card_side = back detect_ps = true detect_risk = true detect_quality = true detect_photo = true detect_card = false detect_direction = true |
即国徽面，返参含义详见 API文档-身份证识别 |
| 3 | 行驶证正页 | vehicle_license | detect_direction = true vehicle_license_side = front unified = false quality_warn = true risk_warn = true |
返参含义详见 API文档-行驶证识别 |
| 4 | 行驶证副页 | vehicle_license_back | detect_direction = true vehicle_license_side = back unified = false quality_warn = true risk_warn = true |
返参含义详见 API文档-行驶证识别 |
| 5 | 驾驶证正页 | driver_license | detect_direction = true driving_license_side = front unified_valid_period = false quality_warn = true risk_warn = true |
支持电子驾驶证正页，返参含义详见 API文档-驾驶证识别 |
| 6 | 驾驶证副页 | driver_license_back | detect_direction = true driving_license_side = back unified_valid_period = false quality_warn = true risk_warn = true |
返参含义详见 API文档-驾驶证识别 |
| 7 | 银行卡 | bank_card | location = true detect_quality = true |
返参含义详见 API文档-银行卡识别 |
| 8 | 大陆护照 | chinese_passport | / | 返参含义详见 API文档-护照识别 |
| 9 | 户口本登记页 | household_register_subpage | household_register_side = subpage | 返参含义详见 API文档-户口本识别 |
| 10 | 户口本户主页 | household_register_homepage | household_register_side = homepage | 返参含义详见 API文档-户口本识别 |
| 11 | 社保卡 | social_security_card | / | 返参含义详见 API文档-社保卡识别 |
| 12 | 房产证 | real_estate_certificate | probability = true location = true |
返参含义详见 API文档-房产证识别 |
| 13 | 财务票据 | multiple_invoice | probability = true location = true verify_parameter = false |
支持增值税发票、卷票、机打发票等13类票据，返参含义详见 API文档-智能财务票据识别 |
| 14 | 营业执照 | biz_license | risk_warn= true detect_quality = true |
返参含义详见 API文档-营业执照 |
| 15 | 港澳居民来往内地通行证正面 | hk_mc_return_passport_front | exitentrypermit_type = hk_mc_return_passport_front probability = true location = true |
即人像面，返参含义详见 API文档-港澳台证件识别 |
| 16 | 港澳居民来往内地通行证反面 | hk_mc_return_passport_back | exitentrypermit_type = hk_mc_return_passport_back probability = true location = true |
返参含义详见 API文档-港澳台证件识别 |
| 17 | 港澳通行证正面 | hk_mc_passport_front | exitentrypermit_type = hk_mc_passport_front probability = true location = true |
即人像面，返参含义详见 API文档-港澳台证件识别 |
| 18 | 港澳通行证反面 | hk_mc_passport_back | exitentrypermit_type = hk_mc_passport_back probability = true location = true |
返参含义详见 API文档-港澳台证件识别 |
| 19 | 台湾居民来往大陆通行证正面 | tw_return_passport_front | exitentrypermit_type = tw_return_passport_front probability = true location = true |
即人像面，返参含义详见 API文档-港澳台证件识别 |
| 20 | 台湾居民来往大陆通行证反面 | tw_return_passport_back | exitentrypermit_type = tw_return_passport_back probability = true location = true |
返参含义详见 API文档-港澳台证件识别 |
| 21 | 台湾通行证正面 | tw_passport_front | exitentrypermit_type = tw_passport_front probability = true location = true |
即人像面，返参含义详见 API文档-港澳台证件识别 |
| 22 | 台湾通行证反面 | tw_passport_back | exitentrypermit_type = tw_passport_back probability = true location = true |
返参含义详见 API文档-港澳台证件识别 |
| 23 | 车辆合格证 | vehicle_certificate | / | 返参详见 API文档-车辆合格证识别 |
| 24 | 快递面单 | waybill | is_identify_virtual_waybill = true | 返参详见 API文档-快递面单识别 |
| 25 | 车牌 | license_plate | multi_detect = true multi_scale = false detect_complete = true detect_risk = true |
返参详见 API文档-车牌识别 |