适用场景身份证识别是许多业务系统的基础能力例如用户实名认证、KYC 核验、酒店入住登记、金融开户、电商实名等。传统人工录入身份证信息效率低、易出错通过 API 可以自动提取姓名、身份证号、性别、地址等结构化字段提升数据准确度和处理速度。接口能力边界支持正反面自动识别是正面还是反面side字段 1 表示正面0 表示反面。返回字段正面返回 6 个字段姓名、身份证号、性别、民族、出生日期、地址反面返回 3 个字段签发机关、有效期起始、有效期截止。图片输入支持 URL 或 Base64 编码字符串Base64 最大 10 MB格式为 jpg/png。QPS 限制2 次/秒适合中低并发场景。鉴权使用 API Key 通过请求头传递保障数据安全。请求参数与鉴权鉴权方式请求头中必须携带X-API-Key字段值为用户的 API Key从控制台获取。X-API-Key: your_api_key_here注意文档可能同时支持Authorization: Bearer token方式请以官方文档为准。本文统一使用X-API-Key。请求方法POST请求地址https://v1.apizero.cn/api/ocr-idcard请求体参数请求体为 JSON 对象包含两个必填字段字段名类型必填描述input_typestring是图片传入方式url或base64input_datastring是图片 URL 或 Base64 编码字符串去掉data:image/...;base64,前缀示例{ input_type: url, input_data: https://example.com/idcard-front.jpg }curl 接入示例以下 curl 命令可直接复制使用请替换X-API-Key和图片地址curl -sS \ -X POST \ -H X-API-Key: your_api_key_here \ -H Content-Type: application/json \ -d {input_type: url, input_data: https://example.com/idcard-front.jpg} \ https://v1.apizero.cn/api/ocr-idcard若使用 Base64 传入建议将 JSON 保存到文件如request.json后使用-d request.json避免命令行过长# request.json 内容 # {input_type: base64, input_data: /9j/4AAQ...完整base64} curl -sS -X POST \ -H X-API-Key: your_api_key_here \ -H Content-Type: application/json \ -d request.json \ https://v1.apizero.cn/api/ocr-idcard返回值解读成功时 HTTP 状态码为 200响应体示例如下{ code: 0, msg: 成功, data: { address: 上海市浦东新区某某路123号, birth: 1990-01-01, gender: 男, identity_code: 310101199001011234, identity_name: 张三, issued_by: null, race: 汉, side: 1, valid_date_end: null, valid_date_start: null }, request_id: req_abc123 }字段说明字段类型说明codeint业务状态码0 表示成功非 0 表示错误msgstring状态描述request_idstring请求唯一标识用于日志排错dataobject识别结果对象data.sideint身份证面1 正面0 反面data.identity_namestring姓名正面data.identity_codestring身份证号正面data.genderstring性别正面data.racestring民族正面data.birthstring出生日期正面格式YYYY-MM-DDdata.addressstring地址正面data.issued_bystring or null签发机关反面data.valid_date_startstring or null有效期起始日期反面data.valid_date_endstring or null有效期截止日期反面当识别正面时issued_by、valid_date_start、valid_date_end为null反面时正面字段为null。常见错误与处理HTTP 状态码codemsg原因处理方式20010001参数错误缺少必填字段或字段类型错误检查请求体 JSON 格式20010002图片下载失败图片 URL 不可访问或格式不支持确保 URL 公网可达图片为 jpg/png20010003识别失败图片模糊、非身份证、反光等调整图片质量或换一张图片401-UnauthorizedAPI Key 无效或未携带检查请求头X-API-Key429-Too Many Requests请求频率超过 QPS 限制降低并发增加重试间隔工程化注意事项1. 图片质量控制Base64 编码后大小不要超过 10 MB建议压缩到 2 MB 以内。保持图片清晰、无反光、文字完整能提高识别成功率。2. 并发与重试QPS 为 2 次/秒建议客户端使用令牌桶或队列限流。遇到 429 或网络错误采用指数退避重试例如 1s, 2s, 4s...。每次请求会返回request_id建议打印到日志便于排查问题。3. 字段判空处理响应中部分字段可能为null例如反面时identity_name为 null后端在读取时需做空值检查避免 NPE。4. 缓存策略对于同一张身份证的重复识别如短时间内多次请求可缓存上一次的结果依据图片指纹或request_id判断减少不必要的 API 调用。5. 隐私与安全图片和识别结果可能包含敏感信息传输必须使用 HTTPS。存储数据时应加密或脱敏例如身份证号只显示前 6 位和后 4 位。代码示例Python以下 Python 代码使用requests库封装了识别函数支持 URL 和本地文件两种方式import requests import base64 API_KEY your_api_key_here URL https://v1.apizero.cn/api/ocr-idcard def recognize_idcard(image_pathNone, image_urlNone): if image_url: payload { input_type: url, input_data: image_url } elif image_path: with open(image_path, rb) as f: b64 base64.b64encode(f.read()).decode(utf-8) payload { input_type: base64, input_data: b64 } else: raise ValueError(请提供图片路径或URL) headers { X-API-Key: API_KEY, Content-Type: application/json } resp requests.post(URL, jsonpayload, headersheaders) result resp.json() if result.get(code) 0: return result[data] else: raise Exception(f识别失败: {result.get(msg)}) # 使用示例 if __name__ __main__: data recognize_idcard(image_urlhttps://example.com/idcard-front.jpg) print(f姓名: {data[identity_name]}, 身份证号: {data[identity_code]})参考文档官方文档https://apizero.cn/aidocs/ocr-idcard原始 Markdownhttps://apizero.cn/aidocs/ocr-idcard/raw.md