# 印刷文字识别(多语种) API 文档

# 接口说明

印刷文字识别(多语种),通过全球领先的 OCR(光学字符识别 Optical Character Recognition)技术,自动对文档 OCR 进行识别,返回文档上的纯文本信息,可以省去用户手动录入的过程, 并会返回图片中文字的坐标位置,方便二次开发。 自动完成文档 OCR 信息的采集,可以很方便对接客户的后台数据系统,给用户带来极大的便利。 该印刷文字识别接口支持语种包括:中(简体和繁体)、英、日、韩、德、法、意、葡、西、荷,接口会自动判断文字语种。

该能力是通过HTTP API的方式给开发者提供一个通用的接口,适用于一次性交互数据传输的AI服务场景,块式传输。相较于SDK,API具有轻量、跨语言的特点,不过请注意该接口使用的HTTP API协议不支持跨域。

# 接口Demo

示例demo请点击 这里 下载。
目前仅提供部分开发语言的demo,其他语言请参照下方接口文档进行开发。
也欢迎热心的开发者到 讯飞开放平台社区 分享你们的demo。

# 接口要求

集成印刷文字识别(多语种)API时,需按照以下要求。

内容 说明
请求协议 http[s] (为提高安全性,强烈推荐https)
请求地址 http[s]: //webapi.xfyun.cn/v1/service/v1/ocr/recognize_document
注:服务器IP不固定,为保证您的接口稳定,请勿通过指定IP的方式调用接口,使用域名方式调用
请求方式 POST
接口鉴权 签名机制,见授权认证
字符编码 UTF-8
响应格式 统一采用JSON格式
开发语言 任意,只要可以向讯飞云服务发起HTTP请求的均可
图片格式 jpg/jpeg
图片属性 推荐设置为:尺寸1024×768,图像质量75以上,位深度24
最短边最小不低于20像素,最大不超过4096像素
图片大小 图像数据按要求编码后(base64编码后进行urlencode)大小不超过4M

# 接口调用流程

注: 调用接口前需配置IP白名单,IP白名单规则请参照 IP白名单

  1. 通过接口密钥基于MD5计算签名,将签名以及其他参数放在Http Request Header中,详见下方 请求头
  2. 将图片数据放在Http Request Body中,以POST表单的形式提交,详见下方 请求体
  3. 向服务器端发送Http请求后,接收服务器端的返回结果,返回结果详见各接口的详细说明。

接口地址示例:

	POST http[s]://webapi.xfyun.cn/v1/service/v1/ocr/recognize_document HTTP/1.1
	Content-Type:application/x-www-form-urlencoded; charset=utf-8

# 白名单

在调用该业务接口时,授权认证通过后,服务端会检查调用方IP是否在讯飞开放平台配置的IP白名单中,对于没有配置到白名单中的IP发来的请求,服务端会拒绝服务。
注:

  • IP白名单,在 控制台-我的应用-相应服务的应用管理卡片上 编辑,保存后五分钟左右生效;
  • 不同Appid的不同服务都需要分别设置IP白名单;
  • 每个IP白名单最多可设置5个IP,IP为外网IP,请勿设置局域网IP;
  • 如果服务器返回结果如下所示(illegal client_ip),则表示由于未配置IP白名单或配置有误,服务端拒绝服务。解决办法请参考 IP白名单问题汇总
{
    "code":"10105",
    "desc":"illegal access|illegal client_ip",
    "data":"",
    "sid":"xxxxxx"
}

# 接口请求参数

# 请求头

Http Request Header 中配置以下参数。

# 授权认证

以下参数用于授权认证:

参数 格式 说明 必须
X-Appid string 讯飞开放平台注册申请应用的应用ID(appid)
X-CurTime string 当前UTC时间戳
从1970年1月1日0点0 分0 秒开始到现在的秒数
X-Param string 相关参数JSON串经Base64编码后的字符串,详见业务参数
X-CheckSum string 令牌,计算方法:MD5(APIKey + X-CurTime + X-Param),三个值拼接的字符串,进行MD5哈希计算(32位小写)

注:

  • APIKey:接口密钥,在讯飞开放平台控制台添加相应服务后即可获取,调用方注意保管,如泄露,可到控制台提交工单联系技术人员重置;
  • X-CheckSum 有效期:出于安全性考虑,每个 X-CheckSum 的有效期为 5 分钟(用 X-CurTime 计算),同时 X-CurTime 要与标准时间同步,否则时间相差太大,服务端会直接认为 X-CurTime 无效;
  • BASE64 编码采用 MIME 格式,字符包括大小写字母各26个,加上10个数字,和加号 + ,斜杠 / ,一共64个字符。

*X-CheckSum *生成示例:

String APIKey="abcd1234"; 
String X-CurTime="1502607694";
String X-Param="eyAiYXVmIjogImF1ZGlvL0wxNjtyYXR...";
String X-CheckSum=MD5(apiKey + X-CurTime + X-Param);

# 业务参数

X-Param 为各配置参数组成的 JSON 串经 BASE64 编码之后的字符串,原始 JSON 串各字段说明如下:

参数 类型 必须 说明 示例
engine_type string 引擎类型,固定为recognize_document recognize_document
imei string 手机序列号 12345678
osid string 操作系统版本 Android
ua string 厂商|全称|机型信息|操作系统版本|分辨率 vivo|vivoY67L|PD1612|ANDROID6.0|720*1280

X-Param生成示例:

	原始JSON串:
	{
	    "engine_type": "recognize_document"
	}
	BASE64编码(即X-Param):
	eyJlbmdpbmVfdHlwZSI6InJlY29nbml6ZV9kb2N1bWVudCJ9

# 请求体

以POST表单的形式提交以下参数:

参数 类型 必须 说明 示例
image string 图像数据
base64编码后进行urlencode
要求base64编码和urlencode后大小不超过4M
仅支持jpg格式
推荐 jpg 文件设置为:尺寸 1024×768,图像质量 75 以上,位深度 24。
exSI6ICJ...

注:

  1. 要求文档图片最短边最小不低于 20 像素,最大不超过 4096 像素。
  2. base64编码后大小会增加约1/3。
  3. 一般基础类库会默认进行urlencode处理,请注意不要重复处理。

# 接口返回参数

返回值为json串,各字段如下:

参数 类型 说明
code string 结果码(具体见SDK&API错误码查询)
data json 详见data说明
desc string 描述
sid string 会话ID

其中sid字段主要用于追查问题,如果出现问题,可以提供sid给讯飞技术人员帮助确认问题。

data各字段说明如下:

字段名 说明
error_msg 引擎错误描述
error_code 引擎错误码
engine_cost 引擎识别耗时,以毫秒为单位
blocks 文字块
lines 文字行
characters 文本行下的characters字段表示文本行中每个字符的坐标、置信度、内容
char_centers 文本行下的char_centers字段表示文本行中每个字符的中心点位置
position 结果文本的位置信息
bounding_box 外接矩形的位置和大小
vertices 文本四个顶点的位置坐标,按照左上、右上、右下、左下顺序排列
score 识别结果置信度
text 文本/字符内容
rotate_angle 倾斜的文本引擎会转正后识别,该字段表示文本块的旋转角度

其中的error_msg和error_code的取值范围及说明对照表:

error_code error_msg 说明
0 ok 正常返回
40001 invalid parameter 参数不对
40002 missing parameter 缺少参数
40003 invalid user or password 账号或密码不对
40004 missing request body 没有HTTP body
40005 invalid image format HTTP body不是图像或者不支持该格式
40006 invalid image size 图片太大或太小
40007 fail to recognize 识别失败
40008 invalid content type 通过HTTP form上传图片时,Content-Type无效
40009 corrupted request body 请求body损坏
40010 fail to extract image 提取图像裸数据失败
50001 backend down 后台服务器宕机
50004 timeout 识别超时
90099 unknown 未知错误

结果示例如下:

失败结果:

	{
	    "code": "10105",
	    "desc": "illegal access|no auth",
	    "data": "",
	    "sid": "wcr00001fa6@dxe4290f1bcfdd6f2b00"
	}

成功结果:

	{
	    "code": "0",
	    "data": {
	        "document": {
	            "blocks": [
	                {
	                    "lines": [
	                        {
	                            "char_centers": [
	                                {
	                                    "x": 38,
	                                    "y": 50
	                                }
	                            ],
	                            "characters": [
	                                {
	                                    "position": {
	                                        "bounding_box": {
	                                            "height": 60,
	                                            "left": 4,
	                                            "top": 20,
	                                            "width": 76
	                                        },
	                                        "vertices": [
	                                            {
	                                                "x": 4,
	                                                "y": 20
	                                            },
	                                            {
	                                                "x": 80,
	                                                "y": 20
	                                            },
	                                            {
	                                                "x": 80,
	                                                "y": 80
	                                            },
	                                            {
	                                                "x": 4,
	                                                "y": 79
	                                            }
	                                        ]
	                                    },
	                                    "score": 0.9999853372573853,
	                                    "text": "劲"
	                                }
	                            ],
	                            "position": {
	                                "bounding_box": {
	                                    "height": 59,
	                                    "left": 5,
	                                    "top": 20,
	                                    "width": 85
	                                },
	                                "vertices": [
	                                    {
	                                        "x": 5,
	                                        "y": 21
	                                    },
	                                    {
	                                        "x": 90,
	                                        "y": 20
	                                    },
	                                    {
	                                        "x": 90,
	                                        "y": 79
	                                    },
	                                    {
	                                        "x": 5,
	                                        "y": 79
	                                    }
	                                ]
	                            },
	                            "score": 0.8800805807113648,
	                            "text": "劲"
	                        }
	                    ],
	                    "position": {
	                        "bounding_box": {
	                            "height": 59,
	                            "left": 5,
	                            "top": 20,
	                            "width": 85
	                        },
	                        "vertices": [
	                            {
	                                "x": 5,
	                                "y": 21
	                            },
	                            {
	                                "x": 90,
	                                "y": 20
	                            },
	                            {
	                                "x": 90,
	                                "y": 79
	                            },
	                            {
	                                "x": 5,
	                                "y": 79
	                            }
	                        ]
	                    }
	                }
	            ],
	            "rotate_angle": 0
	        },
	        "engine_cost": 52.37993240356445,
	        "error_code": 0,
	        "error_msg": "ok"
	    },
	    "desc": "success",
	    "sid": "wcr00001bc3@dx2aab0f1bd0d56f1a00"
	}

# 调用示例

印刷文字识别(多语种)demo go语言

印刷文字识别(多语种)demo php语言

印刷文字识别(多语种)demo python3语言

印刷文字识别(多语种)demo java语言

印刷文字识别(多语种)demo c#语言

印刷文字识别(多语种)demo nodejs语言

# 常见问题

# 印刷文字识别(多语种)主要功能是什么?

答:基于行业领先的光学字符识别技术,将图片上的文字内容,直接转换为可编辑文本。实现高精准、毫秒级识别体验。

# 印刷文字识别(多语种)是否支持sdk

答:暂不支持sdk接入,仅支持webapi

# 印刷文字识别(多语种)支持哪些语言文字?

答:支持中文(简体、繁体)、英、日、韩、德、法、意、葡、西、荷多种语言文字识别。

# 印刷文字识别(多语种)对输入图片有什么要求?

答:图片要求是 jpg/jpeg 格式。

# 印刷文字识别(多语种)能否识别竖排版的文字?

答:文字识别首先是按行进行分好,然后分别识别;不建议识别竖排版的文字,因为识别出来的文字排序是乱的。

# 印刷文字识别(多语种)的收费价格是多少?怎么购买?

答:每个账号免费领取一次3000服务量有效期90天,套餐一:1w次服务量/600元/年,套餐二:10w次服务量/5000元/年,套餐三:100w次服务量/30000元/年,可在控制台对应服务--->实时用量--->购买服务量,套餐详细说明页