身份证识别接口（idcard.ocr）：正反面 12 字段结构化

这个接口能解决什么问题

idcard.ocr 把「实名录入」拆成一次 HTTP 请求。相比传统固定模板 OCR 只能认标准摆拍、遇到倾斜反光就全崩，本接口不依赖固定模板与定位框，能理解证件版式与上下文语义，对轻微模糊、倾斜、反光、褶皱、非标准拍摄角度的证件同样有效，核心字段识别准确率 97%~99%；拿不准的字段返回空字符串而不是猜测值，并给出置信度与质量提示，方便业务侧决定直接采信或转人工复核。

一句话说明

上传身份证照片（正反面均可），一次返回 12 个结构化字段 + 置信度；调用即计费，识别失败同样扣费。

适用场景

用户实名认证、开户与进件
酒店 / 网吧登记、租车与网约车司机资质审核
人力资源入职建档
政务与医保自助终端、代收代付实名校验

接口规格

接口规格
请求地址	`https://api.xujian.tech/openapi/idcard/ocr`
请求方式	POST；支持 multipart/form-data（file 字段）、application/json（image base64）、远程图片地址（imageUrl）
鉴权方式	请求头 `X-API-Key`
接口编码	`idcard.ocr`
收费类型	按次计费（PER_CALL，0.0500 元/次）
计费规则	调用即计费：图片通过校验进入识别流程后，无论成功或失败都计一次费用；未传图片、超 10MB、格式不支持不扣费
图片限制	单张 ≤ 10MB，支持 JPG / PNG / WEBP / BMP / GIF
典型耗时	通常 2 ~ 8 秒
典型用途	实名认证、开户进件、资质审核、入职建档

如何调用

cURL（multipart 上传文件）

curl -s -X POST "https://api.xujian.tech/openapi/idcard/ocr" -H "X-API-Key: 你的APIKey" -F "file=@/path/to/idcard.jpg"

返回示例（人像面，code = 0）

JSON

{
  "code": 0,
  "msg": "success",
  "data": {
    "name": "张三",
    "sex": "男",
    "nation": "汉",
    "birth": "1990-01-01",
    "address": "重庆市巴南区……",
    "idNumber": "50011319900101XXXX",
    "overallConfidence": 0.99,
    "apiCode": "idcard.ocr",
    "apiName": "身份证识别",
    "chargeType": "PER_CALL",
    "balance": 99.9500,
    "costMs": 2800
  }
}

计费说明

按次计费，0.0500 元/次，调用即计费。图片通过校验进入识别流程后，无论识别成功还是失败（模糊无法识别 / 不是身份证 / 上游超时）都计一次费用；只有未传图片、超过 10MB、格式不支持这类参数级错误返回失败且不扣费。

常见问题

正反面都能认吗？ 都能，人像面返回姓名 / 性别 / 民族 / 出生 / 住址 / 公民身份号码，国徽面返回签发机关与有效期。
识别不准的字段怎么办？ 返回空字符串并给出 overallConfidence，业务侧可据此决定直接采信或转人工复核。
为什么识别失败也计费？ 因为已调用视觉模型算力，属于「调用即计费」口径；上传前请确保图片清晰、是身份证。