身份证识别 intsig API

接口说明

身份证识别，通过OCR（光学字符识别 Optical Character Recognition）技术，对身份证正反面图片进行识别，返回身份证图片上的姓名、民族、住址、身份证号、签发机关和有效期等信息，可以省去用户手动录入的过程，自动完成身份证信息的结构化和图像数据的采集，可以很方便对接客户的后台数据系统，给用户带来极大的便利。
采用特有的图像处理技术，在识别身份证图片过程中，还可以对身份证图片进行切边矫正，去除背景图片，并可以获取身份证图片上的头像，方便用户保存。不过请注意，不支持同时识别身份证正反面，正反面需分开在不同的图片进行识别。

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

#接口Demo

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

#接口要求

集成身份证识别API时，需按照以下要求。

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

#接口调用流程

注：若需配置IP白名单，请前往控制台。IP白名单规则请参照 IP白名单。

通过接口密钥基于MD5计算签名，将签名以及其他参数放在Http Request Header中，详见下方请求头。

将图片数据放在Http Request Body中，以POST表单的形式提交，详见下方请求体。

向服务器端发送Http请求后，接收服务器端的返回结果，返回结果详见各接口的详细说明。

接口地址示例：

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

#白名单

在调用该业务接口时

若关闭IP白名单，接口认为IP不限，不会校验IP。

若打开IP白名单，则服务端会检查调用方IP是否在讯飞开放平台配置的IP白名单中，对于没有配置到白名单中的IP发来的请求，服务端会拒绝服务。

IP白名单规则

IP白名单，在控制台-我的应用-相应服务的应用管理卡片上编辑，保存后五分钟左右生效；

不同Appid的不同服务都需要分别设置IP白名单；

IP白名单需设置为外网IP，请勿设置局域网IP；

如果服务器返回结果如下所示(illegal client_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	是	引擎类型，固定为idcard	idcard
head_portrait	string	否	是否返回头像图片：默认head_portrait=0，即不返回头像图片，head_portrait=1，则返回身份证头像照片（Base64编码）	0
crop_image	string	否	是否返回切片图，默认crop_image=0，1表示返回身份证切片照片（Base64编码）	0
id_number_image	string	否	是否返回身份证号码区域截图，默认id_number_image=0，即不返回身份号码区域截图，1表示返回证件号区域截图（Base64编码）	0
recognize_mode	string	否	是否先对图片进行切片后再识别，默认recognize_mode=0，即直接对图片进行识别，1表示采用先切片后识别的模式	0

X-Param生成示例：

	原始JSON串：
	{
	    "engine_type":"idcard",
		"head_portrait": "0",
	    "crop_image": "0"
	}
	BASE64编码（即X-Param）：
	eyJlbmdpbmVfdHlwZSI6ImlkY2FyZCIsImhlYWRfcG9ydHJhaXQiOiAiMCIsImNyb3BfaW1hZ2UiOiAiMCJ9

#请求体

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

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

注： 1）一般基础类库会默认进行urlencode处理，请注意不要重复处理
2）base64编码后大小会增加约1/3

其中的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	未知错误

调用示例

注: demo只是一个简单的调用示例，不适合直接放在复杂多变的生产环境使用

#常见问题

#身份证正反面能否放在一张图片上传

答：不支持同时识别身份证正反面，正反面需分开在不同的图片进行识别。

#身份证识别报40202 非法ip错误

答：需在控制台设置对应ip白名单，一般5-10min生效。

#身份证识别支持哪些地区的身份证？

答：目前身份证识别仅支持识别大陆居民身份证。

#身份证识别多图片有什么要求？

答：图片要求是 jpg/jpeg 格式；建议图片最短边最小不低于 700 像素，最大不超过 4000 像素。

#身份证识别的收费价格是多少？怎么购买？

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

{ "code": "string", "data": { "address": "string", "birthday": "string", "border_covered": true, "complete": true, "error_code": 0, "error_msg": "string", "gray_image": true, "head_blurred": true, "head_covered": true, "id_number": "string", "name": "string", "people": "string", "sex": "string", "time_cost": { "preprocess": 0, "recognize": 0 }, "type": "string" }, "desc": "string", "sid": "string" }

返回响应

🟢200成功

application/json

Body

code

string

必需

data

object

必需

address

string

必需

身份证上的住址识别结果（正面）

birthday

string

必需

身份证上的出生日期识别结果（正面）

border_covered

boolean

必需

border_covered=true 则表示证件边缘判断为不完整

complete

boolean

必需

该字段为保留字段,请忽略

error_code

integer

识别错误码

必需

error_msg

string

错误原因描述

必需

gray_image

boolean

必需

黑白图像 gray_image=true 则表示证件判断为黑白

head_blurred

boolean

必需

头像模糊 head_blurred =true 则表示证件头像判断模糊

head_covered

boolean

必需

边缘遮挡 border_covered=true 则表示证件边缘判断为不完整

id_number

string

必需

身份证上的身份证号码识别结果（正面）

name

string

必需

身份证上的姓名识别结果（正面）

people

string

必需

sex

string

必需

身份证上的性别识别结果（正面）

time_cost

object

必需

type

string

必需

身份证正反面类型当是身份证正面时，type=第二代身份证当是身份证背面时，type=第二代身份证背面当是临时身份证时，type=临时身份证。

desc

string

必需

sid

string

必需

🟠400请求有误

身份证识别 intsig API

接口说明#

#接口Demo#

#接口要求#

#接口调用流程#

#白名单#

#接口请求参数#

#请求头#

#授权认证#

#业务参数#

#请求体#

调用示例#

#常见问题#

#身份证正反面能否放在一张图片上传#

#身份证识别报40202 非法ip错误#

#身份证识别支持哪些地区的身份证？#

#身份证识别多图片有什么要求？#

#身份证识别的收费价格是多少？怎么购买？#

请求参数

返回响应

接口说明

#接口Demo

#接口要求

#接口调用流程

#白名单

#接口请求参数

#请求头

#授权认证

#业务参数

#请求体

调用示例

#常见问题

#身份证正反面能否放在一张图片上传

#身份证识别报40202 非法ip错误

#身份证识别支持哪些地区的身份证？

#身份证识别多图片有什么要求？

#身份证识别的收费价格是多少？怎么购买？