适用场景身份证识别是实名认证流程中不可或缺的一环。典型场景包括用户信息录入通过上传身份证照片自动填充姓名、身份证号、地址等字段减少手动输入错误。KYCKnow Your Customer辅助在金融、租赁、社交平台等场景中快速提取证件信息用于合规审查。身份核验对账将 OCR 结果与用户提交的身份证号、姓名进行比对提升人工审核效率。本 API 支持正面与反面自动判断一次请求即可获取全部 10 个结构化字段适合作为流水线中的一个原子服务。接口能力与限制指标说明端点https://v1.apizero.cn/api/ocr-idcard方法POSTQPS 上限2 次/秒——超过会被限流返回 429输入格式图片 URLjpg/png或 base64 编码字符串≤10 MB输出字段姓名、身份证号、性别、民族、出生日期、地址、签发机关、有效期起止、正反面标识 共 10 个调用前提需在平台登录后获取 API Key并作为 Bearer Token 传入注意该接口目前只返回结构化字段不提供证件照片切割或高清化能力。图片过小200px或模糊时识别准确率会明显下降。鉴权与请求头每次请求必须携带两个Header参数值格式说明AuthorizationBearer 你的 API Key在平台申请 API Key 后填入。注意和空格Bearer 后有一个半角空格Content-Typeapplication/json请求体采用 JSON 格式部分老版 SDK 可能使用X-API-Key头传递建议以官方最新文档为准。本文示例统一使用Authorization: Bearer。请求参数详解请求体为 JSON 对象包含两个必填字段字段类型必填说明input_typestring是取值url或base64表示图片的传递方式input_datastring是当input_typeurl时传入图片的完整 URL为base64时传入图片的 base64 编码字符串不含 data:image/... 前缀参数设计意图分离 type 和 data 可以降低服务端解析维护复杂度若固定为 url则无需检测字符串格式。base64 方式适用于图片已在前端或本地缓存中不需要外网可访问的场景。但注意 base64 编码后体积膨胀约 1/3且 10 MB 的原始图片对应的 base64 字符串可能超过 13 MB实际传输时需考虑请求体大小限制多数网关限制 10–20 MB。最佳实践如果图片存储在对象存储如 OSS、S3或可生成临时外链优先使用input_typeurl减少请求体体积同时可以利用 CDN 加速。如果图片来自本地文件或摄像头拍照后直接处理可使用 base64 编码编码前建议压缩原始图片至 1 MB 以内既能保留文字清晰度又能减少传输时间。额外注意URL 必须为公网可访问的链接内网地址或带鉴权参数的私有地址可能被拒绝。请求示例curl 示例推荐用于快速测试curl -sS -X POST \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d {input_type:url,input_data:https://example.com/idcard-front.jpg} \ https://v1.apizero.cn/api/ocr-idcard将YOUR_API_KEY替换为实际密钥input_data替换为可用的身份证正面图片 URL。成功响应时终端会输出 JSON 字符串。Python 示例使用 requests 库import requests import json url https://v1.apizero.cn/api/ocr-idcard headers { Authorization: Bearer YOUR_API_KEY, Content-Type: application/json } payload { input_type: url, input_data: https://example.com/idcard-front.jpg } response requests.post(url, headersheaders, datajson.dumps(payload)) print(response.status_code) print(response.json())若希望处理 base64 编码注意不要添加data:image/png;base64,前缀仅传入纯 base64 字符串。响应字段说明成功的 HTTP 状态码为 200响应体示例{ code: 0, msg: 成功, request_id: req_abc123, 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 } }顶层字段字段类型说明codeint业务状态码0 表示成功非 0 表示失败见“常见错误”msgstring中文描述信息request_idstring请求唯一标识可用于排查日志dataobject识别结果若失败则为nulldata 内字段详解字段类型说明identity_namestring/null姓名正面反面时为nullidentity_codestring/null身份证号正面genderstring/null性别男 或 女正面racestring/null民族如 汉正面birthstring/null出生日期格式YYYY-MM-DD正面addressstring/null住址正面issued_bystring/null签发机关反面valid_date_startstring/null有效期起始日期反面valid_date_endstring/null有效期截止日期若为长期有效则可能返回长期或null以实际为准sideint1 表示正面人像面0 表示反面国徽面关键注意正面只返回人像面信息姓名、号码等反面只返回签发机关和有效期。当传入图片为正面时issued_by等反向字段为null反之亦然。利用side字段可以验证用户是否上传了正确的页面。部分旧版身份证的地址可能省略“省/市/区”字样字段值按图片中实际印刷内容输出。常见错误码与排查HTTP 状态code值msg示例可能原因与处理2000成功正常识别2001001参数错误缺少input_type或input_data或 content_type 值非法2001002图片下载失败URL 不可达、网络超时、图片内容非 jpg/png2001003图片解析失败base64 格式错误或图片损坏2001004未检测到身份证图片中无身份证或图片过于模糊、倾斜角度过大401-Unauthorized未提供 Authorization 头或 API Key 无效429-Too Many RequestsQPS 超过 2/s需加入本地重试或排队逻辑5xx-服务器错误短暂故障建议指数退避重试 1–3 次排查步骤检查请求头中是否包含正确的 Bearer Token。确认图片格式和大小合规。若返回 1002可用浏览器先访问图片 URL 检查可访问性。若返回 1004尝试调整图片方向正放或提高分辨率。工程化注意事项1. 并发与限流保护QPS 只有 2/s在生产中若需要批量处理大量身份证图片建议使用消息队列如 Redis List 或 RabbitMQ控制消费速率避免触发 429 并导致整体任务失败。2. 图片预处理图片尺寸建议在 500px–2000px 之间太小的图片文字模糊度上升。若传 base64注意在客户端压缩例如 Web 端使用 canvas 调整质量。对于翻拍或扫描件可以先用图像增强库如 OpenCV做灰度化、去噪、纠偏再传给 API。3. 结果校验OCR 输出的姓名、身份证号可能存在个别字符偏差尤其 0/O、1/I 混淆。建议在业务层增加校验身份证号校验前 6 位地区码、出生日期合法性、第 18 位校验码。姓名与用户提交的姓名做模糊匹配或人工二次确认。4. 重试与幂等由于request_id每次请求都会新生成不支持幂等去重。如果同一条图片因超时失败直接重发请求即可接收方不记录图片内容无需担心重复写入。5. 安全与隐私身份证图片包含敏感信息传输时应使用 HTTPS 加密通道若使用 base64避免在日志或错误堆栈中打印完整 payload。建议只记录request_id用于回溯。参考文档官方文档页https://apizero.cn/aidocs/ocr-idcard原始 Markdown 文档https://apizero.cn/aidocs/ocr-idcard/raw.md调用前请务必查阅文档以获取最新参数变更和错误码说明。