# 通用文档识别(大模型) API 文档

# 接口说明

OCR大模型引擎是以讯飞星火大模型为底座研发的新一代OCR识别引擎支持公式、图表、栏目等复杂场景图像识别，具有功能全面、识别效果好、泛化能力强等优点。
该接口是通过 API 的方式给开发者提供一个通用的接口，基于该接口，开发者可以获取开放平台的OCR大模型能力，方便开发者快速集成。
部分开发语言demo如下，其他开发语言请参照文档进行开发，也欢迎热心的开发者到讯飞开放平台社区 (opens new window) 分享你们的demo。
通用OCR大模型 demo Java语言 (opens new window)
集成通用OCR大模型时，需按照以下要求:

内容	说明
传输方式	http[s] (为提高安全性，强烈推荐https)
接口地址	https://cbm01.cn-huabei-1.xf-yun.com/v1/private/se75ocrbm 注：服务器IP不固定，为保证您的接口稳定，请勿通过指定IP的方式调用接口，使用域名方式调用
请求行	POST /v1/private/se75ocrbm HTTP/1.1
接口鉴权	签名机制，详情请参照下方鉴权说明
字符编码	UTF-8
响应格式	统一采用JSON格式
开发语言	任意，只要可以向讯飞云服务发起HTTP请求的均可
适用范围	任意操作系统，但因不支持跨域不适用于浏览器
图片格式	jpg/jpeg/png/bmp
图片大小	base64编码后大小不超过4M

# 鉴权说明

在调用业务接口时，请求方需要对请求进行签名，服务端通过签名来校验请求的合法性。
通过在请求地址后面加上鉴权相关参数的方式，请注意影响鉴权结果的值有url、apiSecret、apiKey、date，如果调试鉴权，请务必按照示例中给的值进行调试，具体参数如下：
http示例url：

https://api.xf-yun.com/v1/private/se75ocrbm?authorization=YXBpX2tleT0iYXBpa2V5WFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFgiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iL21nMmg5QkNrZXNwaWxaOTRIVUJhUVZQcTJ2N1B4WUY5MHRlVEJsYXhkOD0i&host=api.xf-yun.com&date=Wed%2C+11+Aug+2021+06%3A55%3A18+GMT

鉴权参数：

参数	类型	必须	说明	示例
host	string	是	请求主机	api.xf-yun.com
date	string	是	当前时间戳，RFC1123格式("EEE, dd MMM yyyy HH:mm:ss z")	Wed, 11 Aug 2021 06:55:18 GMT
authorization	string	是	使用base64编码的签名相关信息(签名基于hamc-sha256计算)	参考下方详细生成规则

• date参数生成规则：

date必须是UTC+0或GMT时区，RFC1123格式(Wed, 11 Aug 2021 06:55:18 GMT)。
服务端会对date进行时钟偏移检查，最大允许300秒的偏差，超出偏差的请求都将被拒绝。

• authorization参数生成格式：

1）获取接口密钥APIKey 和 APISecret。
在讯飞开放平台控制台，创建一个应用后打开OCR中英文字识别页面可以获取，均为32位字符串。
2）参数authorization base64编码前（authorization_origin）的格式如下。

api_key="$api_key",algorithm="hmac-sha256",headers="host date request-line",signature="$signature"

其中 api_key 是在控制台获取的APIKey，algorithm 是加密算法（仅支持hmac-sha256），headers 是参与签名的参数（见下方注释）。
signature 是使用加密算法对参与签名的参数签名后并使用base64编码的字符串，详见下方。

注： headers是参与签名的参数，请注意是固定的参数名（"host date request-line"），而非这些参数的值。

3）signature的原始字段(signature_origin)规则如下。

signature原始字段由 host，date，request-line三个参数按照格式拼接成，
拼接的格式为(\n为换行符,’:’后面有一个空格)：

host: $host\ndate: $date\n$request-line

假设

请求url = "https://cbm01.cn-huabei-1.xf-yun.com/v1/private/se75ocrbm"
date = "Wed, 11 Aug 2021 06:55:18 GMT"

那么 signature原始字段(signature_origin)则为：

host: api.xf-yun.com
date: Wed, 11 Aug 2021 06:55:18 GMT
POST /v1/private/se75ocrbm HTTP/1.1

4）使用hmac-sha256算法结合apiSecret对signature_origin签名，获得签名后的摘要signature_sha。

signature_sha=hmac-sha256(signature_origin,$apiSecret)

其中 apiSecret 是在控制台获取的APISecret

5）使用base64编码对signature_sha进行编码获得最终的signature。

signature=base64(signature_sha)

假设

APISecret = "apisecretXXXXXXXXXXXXXXXXXXXXXXX"	
date = "Wed, 11 Aug 2021 06:55:18 GMT"

则signature为

signature="/mg2h9BCkespilZ94HUBaQVPq2v7PxYF90teTBlaxd8="

6）根据以上信息拼接authorization base64编码前（authorization_origin）的字符串，示例如下。

api_key="apikeyXXXXXXXXXXXXXXXXXXXXXXXXXX", algorithm="hmac-sha256", headers="host date request-line", signature="/mg2h9BCkespilZ94HUBaQVPq2v7PxYF90teTBlaxd8="

注： headers是参与签名的参数，请注意是固定的参数名（"host date request-line"），而非这些参数的值。

7）最后再对authorization_origin进行base64编码获得最终的authorization参数。

authorization = base64(authorization_origin)
示例结果为：
authorization=YXBpX2tleT0iYXBpa2V5WFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFgiLCBhbGdvcml0aG09ImhtYWMtc2hhMjU2IiwgaGVhZGVycz0iaG9zdCBkYXRlIHJlcXVlc3QtbGluZSIsIHNpZ25hdHVyZT0iL21nMmg5QkNrZXNwaWxaOTRIVUJhUVZQcTJ2N1B4WUY5MHRlVEJsYXhkOD0i

# 鉴权结果

如果鉴权失败，则根据不同错误类型返回不同HTTP Code状态码，同时携带错误描述信息，详细错误说明如下：

HTTP Code	说明	错误描述信息	解决方法
401	缺少authorization参数	{"message":"Unauthorized"}	检查是否有authorization参数，详情见authorization参数详细生成规则
401	签名参数解析失败	{“message”:”HMAC signature cannot be verified”}	检查签名的各个参数是否有缺失是否正确，特别确认下复制的api_key是否正确
401	签名校验失败	{“message”:”HMAC signature does not match”}	签名验证失败，可能原因有很多。 1. 检查api_key,api_secret 是否正确。 2.检查计算签名的参数host，date，request-line是否按照协议要求拼接。 3. 检查signature签名的base64长度是否正常(正常44个字节)。
403	时钟偏移校验失败	{“message”:”HMAC signature cannot be verified, a valid date or x-date header is required for HMAC Authentication”}	检查服务器时间是否标准，相差5分钟以上会报此错误

时钟偏移校验失败示例：

HTTP/1.1 403 Forbidden
Date: Mon, 30 Nov 2020 02:34:33 GMT
Content-Length: 116
Content-Type: text/plain; charset=utf-8
{
    "message": "HMAC signature does not match, a valid date or x-date header is required for HMAC Authentication"
}

# 请求

接口地址：

https://cbm01.cn-huabei-1.xf-yun.com/v1/private/se75ocrbm

在调用业务接口时，都需要在 Http Request Body 中配置以下参数，请求数据均为json字符串。
请求协议示例：

{
    "header": {
        "app_id": "123456",
        "uid": "39769795890",
        "did": "SR082321940000200",
        "imei": "8664020318693660",
        "imsi": "4600264952729100",
        "mac": "6c:92:bf:65:c6:14",
        "net_type": "wifi",
        "net_isp": "CMCC",
        "status": 0,
        "request_id": null,
        "res_id": ""
    },
    "parameter": {
        "ocr": {
            "result_option": "normal",
            "result_format": "json",
            "output_type": "one_shot",
            "exif_option": "0",
            "json_element_option": "",
            "markdown_element_option": "watermark=0,page_header=0,page_footer=0,page_number=0,graph=0",
            "sed_element_option": "watermark=0,page_header=0,page_footer=0,page_number=0,graph=0",
            "alpha_option": "0",
            "rotation_min_angle": 5,
            "result": {
                "encoding": "utf8",
                "compress": "raw",
                "format": "plain"
            }
        }
    },
    "payload": {
        "image": {
            "encoding": "jpg",
            "image": "",
            "status": 0,
            "seq": 0
        }
    }
}

协议结构说明：

字段	含义	类型	描述
header	协议头部	Object	协议头部，用于描述平台特性的参数，详见下方平台参数。
parameter	能力参数	Object	AI 特性参数，用于控制 AI 引擎特性的开关。
ocr	服务别名	Object
result	响应数据控制	Object	数据格式预期，用于描述返回结果的编码等相关约束，不同的数据类型，约束维度亦不相同，此 object 与响应结果存在对应关系
payload	输入数据段	Object	数据段，携带请求的数据。
image	输入数据	Object	输入数据，详见下方请求数据

# 请求参数说明

# 平台参数

字段	含义	类型	限制	是否必传
app_id	在平台申请的app id信息	string	"maxLength":50	是
uid	请求用户服务返回的uid，用户及设备级别个性化功能依赖此参数	string	"maxLength":50	否
did	请求方确保唯一的设备标志，设备级别个性化功能依赖此参数	string	"maxLength":50	否
imei	设备imei信息	string	"maxLength":50	否
imsi	设备imsi信息	string	"maxLength":50	否
mac	设备mac信息	string	"maxLength":50	否
net_type	网络类型，可选值为wifi、2G、3G、4G、5G	string	wifi、2G、3G、4G、5G	否
net_isp	运营商信息，可选值为CMCC、CUCC、CTCC、other	string	CMCC、CUCC、CTCC、other	否
request_id	客户端请求的会话唯一标识	string	"maxLength":64	否
res_id	个性化资源ID	string	"maxLength":1024	否
status	请求状态，可选值为：0 - 开始、1 - 继续、2 - 结束	int	0、1、2	是

# 服务特性参数

功能参数

功能标识	功能描述	数据类型	取值范围	必填	默认值
result_option	输出结果级别，以逗号分隔，默认为“normal”，取值范围可枚举	string	normal:输出OCR识别结果和行坐标, normal,char:输出OCR识别结果和字符单元（CharUnit）结果, normal,no_line_position:输出不带行坐标的OCR识别结果, normal,char,no_line_position:输出不带行坐标的OCR识别结果、字符单元（CharUnit）结果	否	normal
result_format	输出结果格式,默认为“json”，取值范围可枚举	string	json:输出结果为JSON字符串格式, json,markdown:输出结果为json、markdown格式, json,sed:输出结果为json、简单要素文档（sed）格式, json,markdown,sed:输出结果为json、markdown、简单要素文档（sed）格式	否	json
output_type	结果输出方式，默认为”one_shot”，取值范围可枚举，当前版本仅支持one_shot	string	one_shot:一次性输出全量结果, streaming_layout:流式输出两次，第一次输出版面信息，第二次输出全量结果	否	one_shot
exif_option	是否解析图片exif头，默认为“0”，取值范围可枚举	string	0:不解析, 1:解析	否	0
json_element_option	(保留字段暂不支持)默认为空字符串，所有要素均输出；针对每个要素有特殊需求时可使用本参数进行设定输入格式为: “element_name1=value1,element_name2=value2”	string	最小长度:0, 最大长度:1000	否
markdown_element_option	默认为空字符串，所有要素均输出；针对每个要素有特殊需求时可使用本参数进行设定，输入格式为: “element_name1=value1,element_name2=value2”其中element_name可选值有：seal:印章，information_bar:信息栏，fingerprint:手印，qrcode:二维码，watermark:水印，barcode:条形码，page_header:页眉，page_footer:页脚，page_number:页码，layout:版面，title:标题，region:区域，paragraph:段落，textline:文本行，table:表格，graph:插图，list:列表，pseudocode:伪代码，code:代码，footnote:脚注，formula:公式；value值可选值有：0:不输出，1:输出，默认值；说明：当element_name为table时，1表示同时识别有线表和少线表，2表示只识别有线表。	string	最小长度:0, 最大长度:1000	否	watermark=0,page_header=0,page_footer=0,page_number=0,graph=0
sed_element_option	默认为空字符串，所有要素均输出；针对每个要素有特殊需求时可使用本参数进行设定，输入格式为:“element_name1=value1,element_name2=value2”其中element_name可选值有：seal:印章，information_bar:信息栏，fingerprint:手印，qrcode:二维码，watermark:水印，barcode:条形码，page_header:页眉，page_footer:页脚，page_number:页码，layout:版面，title:标题，region:区域，paragraph:段落，textline:文本行，table:表格，graph:插图，list:列表，pseudocode:伪代码，code:代码，footnote:脚注，formula:公式；value值可选值有：0:不输出，1:输出，默认值；说明：当element_name为table时，1表示同时识别有线表和少线表，2表示只识别有线表。	string	最小长度:0, 最大长度:1000	否	watermark=0,page_header=0,page_footer=0,page_number=0,graph=0
alpha_option	是否解析图片的alpha通道，默认为“0”，取值范围可枚举	string	0:不解析图片的alpha通道，即仅读取图片的RGB通道。若alpha通道为透明（即alpha通道的值为0）的区域存在文字，该区域的文字不可见，但识别结果中会出现该区域的文字，即出现识别结果与看到的内容不一致的现象, 1:解析图片的alpha通道，若图片存在alpha通道，将alpha通道为透明（alpha通道的值为0）的像素的RGB值设为白色（#FFFFFF），若alpha通道为透明的区域存在文字，识别结果中不会出现透明区域的文字，即识别结果与看到的内容保持一致。	否	0
rotation_min_angle	图像的最小旋转角度阈值，当图像绕中心顺、逆时针旋转的角度绝对值超过该阈值时，对图像进行旋转，取值范围为[0,180]，其中： 0：有旋转角度的图像均进行旋转。 180：所有图像均不进行旋转。默认值为“5”，即当图像旋转角度的绝对值超过5°时才进行旋转。	float	最小值:0, 最大值:180	否	5

响应数据参数 result 段的参数（默认返回）

字段	含义	数据类型	取值范围	默认值	说明	必填
encoding	文本编码	string	utf8, gb2312, gbk	utf8	取值范围可枚举	否
compress	文本压缩格式	string	raw, gzip	raw	取值范围可枚举	否
format	文本格式	string	plain, json, xml	plain	取值范围可枚举	否

# 请求数据

image（默认请求）

字段	含义	数据类型	取值范围	默认值	说明	必填
encoding	图像编码	string	jpg:jpg格式, jpeg:jpeg格式, png:png格式, bmp:bmp格式	jpg	图像编码	否
image	图像数据	string	最小尺寸:1B, 最大尺寸:10485760B		需base64编码，图片大小：0~10M	是
status	数据状态	int	0:开始, 1:继续, 2:结束		流式传输	是
seq	数据序号	int	最小值:0, 最大值:9999999	0	标明数据为第几块	否

# 响应

响应协议示例：

{
    "header": {
        "code": 0,
        "message": "success",
        "sid": "ase000704fa@dx16ade44e4d87a1c802",
        "status": 0
    },
    "payload": {
        "result": {
            "encoding": "utf8",
            "compress": "raw",
            "format": "plain",
            "status": 0,
            "seq": 0,
            "text": ""
        }
    }
}

协议结构说明：

字段	含义	类型	说明
header	协议头部	Object	协议头部，用于描述平台特性的参数，详见下方平台参数。
payload	响应数据块	Object	数据段，携带响应的数据。
result	响应数据块	Object	输出数据，详见下方响应数据参数。

# 响应参数说明

# 平台参数

字段	含义	类型	是否必选
code	返回码，0表示成功，其它表示异常	int	是
message	错误描述	string	是
sid	本次会话的id	string	是

# 响应数据参数

result（默认返回）

字段	含义	数据类型	取值范围	默认值	说明	必填
encoding	文本编码	string	utf8, gb2312, gbk	utf8	取值范围可枚举	否
compress	文本压缩格式	string	raw, gzip	raw	取值范围可枚举	否
format	文本格式	string	plain, json, xml	plain	取值范围可枚举	否
status	数据状态	int	0:开始, 1:继续, 2:结束		流式传输	是
seq	数据序号	int	最小值:0, 最大值:9999999		数据序号	是
text	文本数据	string	最小尺寸:1B, 最大尺寸:1048576B		需base64编码，文本大小：0 - 1M	是

# 错误码列表

错误码示例：

{
    "code":10003, // 平台通用错误码，详细信息请参照 5.1 平台通用错误码
    "message":"WrapperInitErr;errno=101", // errno 为引擎错误码
    "sid":"ocr00088c7d@dx170194697e9a11d902"
}

# 平台通用错误码

错误码	错误描述	说明	处理策略
10009	input invalid data	输入数据非法	检查输入数据
10010	service license not enough	没有授权许可或授权数已满	提交工单
10019	service read buffer timeout, session timeout	session超时	检查是否数据发送完毕但未关闭连接
10043	Syscall AudioCodingDecode error	音频解码失败	检查aue参数，如果为speex，请确保音频是speex音频并分段压缩且与帧大小一致
10114	session timeout	session 超时	会话时间超时，检查是否发送数据时间超过了60s
10139	invalid param	参数错误	检查参数是否正确
10160	parse request json error	请求数据格式非法	检查请求数据是否是合法的json
10161	parse base64 string error	base64解码失败	检查发送的数据是否使用base64编码了
10163	param validate error:...	参数校验失败	具体原因见详细的描述
10200	read data timeout	读取数据超时	检查是否累计10s未发送数据并且未关闭连接
10222	context deadline exceeded	1.上传的数据超过了接口上限； 2.SSL证书无效；	1.检查接口上传的数据（文本、音频、图片等）是否超越了接口的最大限制，可到相应的接口文档查询具体的上限； 2. 请将log导出发到工单：https://console.xfyun.cn/workorder/commit；
10223	RemoteLB: can't find valued addr	lb 找不到节点	提交工单
10313	invalid appid	appid和apikey不匹配	检查appid是否合法
10317	invalid version	版本非法	请到控制台提交工单联系技术人员
10700	not authority	引擎异常	按照报错原因的描述，对照开发文档检查输入输出，如果仍然无法排除问题，请提供sid以及接口返回的错误信息，到控制台提交工单联系技术人员排查。
11200	auth no license	功能未授权	请先检查appid是否正确，并且确保该appid下添加了相关服务。若没问题，则按照如下方法排查。 1. 确认总调用量是否已超越限制，或者总次数授权已到期，若已超限或者已过期请联系商务人员。 2. 查看是否使用了未授权的功能，或者授权已过期。
11201	auth no enough license	该APPID的每日交互次数超过限制	根据自身情况提交应用审核进行服务量提额，或者联系商务购买企业级正式接口，获得海量服务量权限以便商用。
11503	server error :atmos return an error data	服务内部响应数据错误	提交工单
11502	server error: too many datas in resp	服务配置错误	提交工单
100001~100010	WrapperInitErr	调用引擎时出现错误	请根据message中包含的errno前往 5.2引擎错误码查看对应的说明及处理策略

在这篇文章中：