1. 接口说明

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

注:不支持同一张图片上同时识别身份证正反面。

2. 接口地址

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

3. 请求参数

在 Http Request Header 中配置授权认证参数,见【接口描述-授权认证。 其中 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

在 Http Request Body 中配置以下参数:

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

注: base64编码后大小会增加约1/3

4. 返回值

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

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

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

data各字段说明如下:

参数 说明 备注
name 姓名 身份证上的姓名识别结果
id_number 身份证号 身份证上的身份证号码识别结果
birthday 出生日期 身份证上的出生日期识别结果
sex 性别 身份证上的性别识别结果
people 民族 身份证上的民族识别结果
address 住址 身份证上的住址识别结果
issue_authority 签发机关 身份证上的签发机关识别结果
validity 有效期 身份证上的有效期识别结果
cropped_image 身份证切边图片 身份证正面或反面的切边图片,base64编码
id_number_image 身份证号码截图 身份证正面身份证号截图,base64编码
head_portrait 身份证正面头像信息 身份证正面头像信息的KEY值
image 身份证正面头像截图 身份证正面头像截图,base64编码
type 类型 身份证正反面类型;当是身份证正面时,type=第二代身份证;当是身份证背面时,type=第二代身份证背面。当是临时身份证时,type=临时身份证。
gray_image 黑白图像 gray_image=true 则表示证件判断为黑白
complete 证件完整 complete=true 则表示证件判断为不完整
border_covered 边缘遮挡 border_covered=true 则表示证件边缘判断为不完整
head_blurred 头像模糊 head_blurred =true 则表示证件头像判断模糊
error_code 错误码 识别错误码
error_msg 错误信息 错误原因描述

其中的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": "10106",
    "desc": "invalid parameter|invalid X-Appid",
    "data": "",
    "sid": "wcr0000bb3f@dx3d5c059d83b3477200"
}

成功结果:

{
"code": "0",
"data": {
    "address": "广东省清新县浸潭镇鸡见坑村委会下围村2号",
    "birthday": "1992年8月22日",
    "border_covered": false,
    "complete": true,
    "error_code": 0,
    "error_msg": "ok",
    "gray_image": false,
    "head_blurred": false,
    "head_covered": false,
    "id_number": "666667777788888999",
    "name": "张三",
    "people": "汉",
    "sex": "男",
    "type": "第二代身份证"
},
"desc": "success",
"sid": "wcr00000001@dx11730e79150f000100"
}

5. 调用示例

python2.7 脚本示例

说明:将脚本中IMAGE_PATH, API_KEY, APPID, 换成相应的图片路径,讯飞开放平台提供的apiKey,讯飞开放平台应用的appid即可,运行脚本可打印相应结果。

#!/usr/bin/python
# -*- coding: UTF-8 -*-
import urllib2
import time
import urllib
import json
import hashlib
import base64


def main():
    f = open("IMAGE_PATH", 'rb')
    file_content = f.read()
    base64_image = base64.b64encode(file_content)
    body = urllib.urlencode({'image': base64_image})

    url = 'http://webapi.xfyun.cn/v1/service/v1/ocr/idcard'
    api_key = 'API_KEY'
    param = {"engine_type": "idcard", "head_portrait": "0"}

    x_appid = 'APPID'
    x_param = base64.b64encode(json.dumps(param).replace(' ', ''))
    x_time = int(int(round(time.time() * 1000)) / 1000)
    x_checksum = hashlib.md5(api_key + str(x_time) + x_param).hexdigest()
    x_header = {'X-Appid': x_appid,
                'X-CurTime': x_time,
                'X-Param': x_param,
                'X-CheckSum': x_checksum}
    req = urllib2.Request(url, body, x_header)
    result = urllib2.urlopen(req)
    result = result.read()
    print result
    return


if __name__ == '__main__':
    main()

6. 错误码

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 未知错误
Copyright © iflytek.com 2018 all right reserved,powered by Gitbook该文件修订时间: 2018-10-19 20:53:23

results matching ""

    No results matching ""