接入文档
证件OCR识别
外国人永居证识别接入
API接入
API接入
# 描述
检测和识别中华人民共和国外国人永久居留证。
# 调用URL
https://api.megvii.com/faceid/v5/ocr_foreign_pr_card
注意：在生产环境中，请使用HTTPS的通信方式。HTTP方式的通信属于不安全链路，存在安全风险，请勿在生产环境中使用。在生产环境中使用HTTP方式的，将无法得到服务可靠性保障。
# 调用方法
POST 注意：用form-data格式请求
| 必选/可选 | 参数名 | 类型 | 参数说明 |
| 必选 | sign | String | 调用此API客户的签名，具体的签名产生方式请查阅[鉴权](v5_authentication) |
| sign_version | String | 签名算法版本号，请传递：hmac_sha1 | |
| image | File |
一个图片，二进制文件，需要用Post Multipart/Form-Data的方式上传
注：图片的文件大小小于10MB。支持的图片最小是200x200像素，最大是8000x8000像素 |
|
| 可选 | return_portrait | String |
设定是否返回永居证上的人像（仅当传入的永居证人像面图片，且识别到人脸才会返回，若没有识别到人脸，则不返回）
|
| exception_range | JsonObject |
用于自定义纳入1002的异常情况的范围，可设置以下字段：
|
|
| encryption_type | String |
设定是否开启传输数据加密
|
# 返回值说明
外国人永居证分为新版与旧版，新旧两版在参数返回上没有区别。仅由于新版和旧版永居证号字段长度不同，返回结果的长度也会不同
| 返回值条件 | 字段 | 类型 | 说明 |
|---|---|---|---|
| 都会返回右列的值 | request_id | String | 用于区分每一次请求的唯一的字符串。除非发生404（API_NOT_FOUND）或403（AUTHORIZATION_ERROR）错误，此字段必定返回 |
| result | Int |
识别的结果信息：
|
|
| 返回对应的字段 | name_eng | Dict | 英文姓名（示例：“Andrew Lee”）。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 |
| name_chs | Dict | 中文姓名。可以为null。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |
| gender | Dict | 性别（男/M或女/F）。该字段为字典类型，相关的结构体信息请参照下面的"字段的结构体信息"表格 | |
| date_of_birth | Dict | 出生年月日。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |
| nationality | Dict | 国籍（示例：加拿大/CAN）。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |
| valid_date_start | Dict | 有效期的开始日期。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |
| valid_date_end | Dict | 有效期的结束日期。该字段为字典类型，相关的结构体信息请参照下面的“字段的结构体信息”表格 | |
| idcard_number | Dict | 永居证号。该字段为字典类型，相关的结构体信息请参照下面的"字段的结构体信息"表格 | |
| portrait | Dict | 永居证图片上的头像图片，仅在return_portrait参数设定为1时返回，头像照片采用JPG格式的base64表示 | |
| 都会返回右列的值 | completeness | Int |
表示永居证图片的完整性，平整性
|
| card_rect | Dict |
返回图片里面，永居证卡片的四点坐标，坐标的开始位置为图片左上角，具体返回示例如下：
"rt"{ "y":43, "x":927 } //右上角坐标 "lt"{ "y":33, "x":58 } //左上角坐标 "lb"{ "y":586, "x":59 } //左下角坐标 "rb"{ "y":580, "x":920 } //右下角坐标 注：当字段的区域没有识别出来的时候，各个坐标点的x和y均返回为0 |
|
| ERROR | String | 发生错误后，会返回对应的错误码，具体见下面 ERROR 错误信息 |
# 字段的结构体信息
| +result | String | 表示字段识别出来的内容，若没有识别到，则返回空字符串 |
| +quality | Float |
表示该区域是否存在质量问题（存在影响识别的光斑、阴影、遮挡、污渍等）。取［0，1］区间实数，3位有效数字
注：
|
| +rect | Dict |
返回字典结构，里面包含该字段区域的四点坐标，具体返回示例如下：
"rt"{ "y":43, "x":927 } //右上角坐标 "lt"{ "y":33, "x":58 } //左上角坐标 "lb"{ "y":586, "x":59 } //左下角坐标 "rb"{ "y":580, "x":920 } //右下角坐标 注：当字段的区域没有识别出来的时候，各个坐标点的x和y均返回为0 |
| +logic | Int |
表示该字段是否存在逻辑问题。如：识别永居证号因遮挡无法识别到18位、永居证号码的最后一位和性别匹配不上。通常当有逻辑问题的时候，认为识别出的结果是不可信的
|
# 返回值示例
新版
{
"result": 1002,
"completeness": 1,
"name_eng": {
"quality": 0.956,
"result": "Andrew Lee",
"rect": {
"rt": {
"y": 137,
"x": 385
},
"lt": {
"y": 136,
"x": 271
},
"lb": {
"y": 180,
"x": 271
},
"rb": {
"y": 181,
"x": 385
}
},
"logic": 0
},
"name_chs": {
"quality": 0.956,
"result": "张三",
"rect": {
"rt": {
"y": 190,
"x": 385
},
"lt": {
"y": 189,
"x": 271
},
"lb": {
"y": 240,
"x": 271
},
"rb": {
"y": 239,
"x": 385
}
},
"logic": 0
},
"time_used": 442,
"gender": {
"quality": 0.968,
"result": "女",
"rect": {
"rt": {
"y": 225,
"x": 309
},
"lt": {
"y": 225,
"x": 275
},
"lb": {
"y": 261,
"x": 275
},
"rb": {
"y": 261,
"x": 309
}
},
"logic": 0
},
"card_rect": {
"rt": {
"y": 55,
"x": 1126
},
"lt": {
"y": 49,
"x": 89
},
"lb": {
"y": 680,
"x": 100
},
"rb": {
"y": 695,
"x": 1101
}
},
"request_id": "1526629075,8dcd4722-9f2b-42ca-a2c3-bae3a061b20f",
"idcard_number": {
"quality": 0.007,
"result": "911xxxxxx123456789",
"rect": {
"rt": {
"y": 593,
"x": 970
},
"lt": {
"y": 586,
"x": 416
},
"lb": {
"y": 622,
"x": 416
},
"rb": {
"y": 630,
"x": 968
}
},
"logic": 1
},
"date_of_birth": {
"quality": 0.995,
"result": "1989.11.19",
"rect": {
"rt": {
"y": 306,
"x": 459
},
"lt": {
"y": 306,
"x": 435
},
"lb": {
"y": 337,
"x": 435
},
"rb": {
"y": 337,
"x": 459
}
},
"logic": 1
},
"portrait": {
"quality": 0,
"result": "/9j/4AAQSkZJRgABA...", //Base64字符串
"rect": {
"rt": {
"y": 307,
"x": 559
},
"lt": {
"y": 306,
"x": 526
},
"lb": {
"y": 338,
"x": 526
},
"rb": {
"y": 338,
"x": 558
}
},
"logic": 0
},
"nationality": {
"quality": 0.995,
"result": "加拿大/CAN",
"rect": {
"rt": {
"y": 307,
"x": 559
},
"lt": {
"y": 306,
"x": 526
},
"lb": {
"y": 338,
"x": 526
},
"rb": {
"y": 338,
"x": 558
}
},
"logic": 0
},
"valid_date_start": {
"quality": 0.983,
"result": "2024.1.1",
"rect": {
"rt": {
"y": 303,
"x": 347
},
"lt": {
"y": 303,
"x": 272
},
"lb": {
"y": 334,
"x": 272
},
"rb": {
"y": 335,
"x": 347
}
},
"logic": 1
},
"valid_date_end": {
"quality": 0.983,
"result": "2034.1.1",
"rect": {
"rt": {
"y": 303,
"x": 347
},
"lt": {
"y": 303,
"x": 272
},
"lb": {
"y": 334,
"x": 272
},
"rb": {
"y": 335,
"x": 347
}
},
"logic": 1
},
}
旧版
{
"result": 1002,
"completeness": 1,
"name_eng": {
"quality": 0.956,
"result": "Andrew Lee",
"rect": {
"rt": {
"y": 137,
"x": 385
},
"lt": {
"y": 136,
"x": 271
},
"lb": {
"y": 180,
"x": 271
},
"rb": {
"y": 181,
"x": 385
}
},
"logic": 0
},
"name_chs": {
"quality": 0.956,
"result": "张三",
"rect": {
"rt": {
"y": 190,
"x": 385
},
"lt": {
"y": 189,
"x": 271
},
"lb": {
"y": 240,
"x": 271
},
"rb": {
"y": 239,
"x": 385
}
},
"logic": 0
},
"time_used": 442,
"gender": {
"quality": 0.968,
"result": "女",
"rect": {
"rt": {
"y": 225,
"x": 309
},
"lt": {
"y": 225,
"x": 275
},
"lb": {
"y": 261,
"x": 275
},
"rb": {
"y": 261,
"x": 309
}
},
"logic": 0
},
"card_rect": {
"rt": {
"y": 55,
"x": 1126
},
"lt": {
"y": 49,
"x": 89
},
"lb": {
"y": 680,
"x": 100
},
"rb": {
"y": 695,
"x": 1101
}
},
"request_id": "1526629075,8dcd4722-9f2b-42ca-a2c3-bae3a061b20f",
"idcard_number": {
"quality": 0.007,
"result": "CANxxxxxx123456",
"rect": {
"rt": {
"y": 593,
"x": 970
},
"lt": {
"y": 586,
"x": 416
},
"lb": {
"y": 622,
"x": 416
},
"rb": {
"y": 630,
"x": 968
}
},
"logic": 1
},
"date_of_birth": {
"quality": 0.995,
"result": "1989.11.19",
"rect": {
"rt": {
"y": 306,
"x": 459
},
"lt": {
"y": 306,
"x": 435
},
"lb": {
"y": 337,
"x": 435
},
"rb": {
"y": 337,
"x": 459
}
},
"logic": 1
},
"portrait": {
"quality": 0,
"result": "/9j/4AAQSkZJRgABA...", //Base64字符串
"rect": {
"rt": {
"y": 307,
"x": 559
},
"lt": {
"y": 306,
"x": 526
},
"lb": {
"y": 338,
"x": 526
},
"rb": {
"y": 338,
"x": 558
}
},
"logic": 0
},
"nationality": {
"quality": 0.995,
"result": "加拿大/CAN",
"rect": {
"rt": {
"y": 307,
"x": 559
},
"lt": {
"y": 306,
"x": 526
},
"lb": {
"y": 338,
"x": 526
},
"rb": {
"y": 338,
"x": 558
}
},
"logic": 0
},
"valid_date_start": {
"quality": 0.983,
"result": "2024.1.1",
"rect": {
"rt": {
"y": 303,
"x": 347
},
"lt": {
"y": 303,
"x": 272
},
"lb": {
"y": 334,
"x": 272
},
"rb": {
"y": 335,
"x": 347
}
},
"logic": 1
},
"valid_date_end": {
"quality": 0.983,
"result": "2034.1.1",
"rect": {
"rt": {
"y": 303,
"x": 347
},
"lt": {
"y": 303,
"x": 272
},
"lb": {
"y": 334,
"x": 272
},
"rb": {
"y": 335,
"x": 347
}
},
"logic": 1
},
}
# 特殊的ERROR
| HTTP 状态代码 | 错误信息 | 说明 |
|---|---|---|
| 400 | ID_CARD_NOT_FOUND | 图片中没有找到永居证 |
| 400 | INVALID_IMAGE_SIZE: image | 图片的像素不符合要求，图片像素多大或者过小 |
| 400 | IMAGE_ERROR_UNSUPPORTED_FORMAT: image | 图片解析失败 |
# 错误信息
HTTP 状态代码 |
错误信息 | 说明 |
|---|---|---|
| 400 | BAD_ARGUMENTS: <key> | 某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长，或者照片无法解析） |
| 400 | MISSING_ARGUMENTS: <key> | 缺少某个必选参数 |
| 400 | KEY_NOT_FOUND | encryption_type开启加密，但未配置加密公钥和解密私钥 |
| 403 | AUTHENTICATION_ERROR | sign不匹配 |
| 403 | AUTHORIZATION_ERROR:<reason> | 账号被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限。<reason>取值："DENIED." : 账号无权限或被停用"Limit reached." : 这个账号对当前API的调用量达到上限。 |
| 403 | CONCURRENCY_LIMIT_EXCEEDED | 并发数超过限制 |
| 404 | API_NOT_FOUND | 所调用的API不存在 |
| 413 | Request Entity Too Large | 客户发送的请求大小或单张照片大小超过了10MB。该错误的返回格式为纯文本，不是json格式 |
| 500 | INTERNAL_ERROR | 服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系 FaceID 客服或商务 |
该文档未解决您的疑问？
查看常见问题
查看常见问题