华为云用户手册

请求消息体 请求消息体通常以结构化格式发出，与请求消息头中Content-type对应，传递除请求消息头之外的内容。若请求消息体中参数支持中文，则中文字符必须为UTF-8编码。 每个接口的请求消息体内容不同，也并不是每个接口都需要有请求消息体（或者说消息体为空），GET、DELETE操作类型的接口就不需要消息体，消息体具体内容需要根据具体接口而定。 对于 人证核身 标准版（三要素）接口，您可以从接口的请求部分看到所需的请求参数及参数说明。将消息体加入后的请求如下所示。 POST https://ivs.cn-north-4.myhuaweicloud.com/v2.0/ivs-standard Request Header: Content-Type: application/json X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT...Request Body:{ "meta": { "uuid": "user_defined" }, "data": { "req_data": [ { "idcard_image1": "/9j/4AAQSkZJRgABAgEASA...", "idcard_image2": "/9j/4AAAAABQSkZJRgABAgEASB...", "face_image": "/9j/4BBQSkZJRgABAgEASB..." } ] }} 到这里为止这个请求需要的内容就具备齐全了，您可以使用curl、Postman或直接编写代码等方式发送请求调用API。

请求消息头 附加请求头字段，如指定的URI和HTTP方法所要求的字段。例如定义消息体类型的请求头“Content-Type”，请求鉴权信息等。 如下公共消息头需要添加到请求中。 Content-Type：消息体的类型（格式），必选，默认取值为“application/json”，有其他取值时会在具体接口中专门说明。 X-Auth-Token：用户Token，可选，当使用Token方式认证时，必须填充该字段。用户Token请参考认证鉴权。 添加消息头后的请求如下所示。 POST https://ivs.cn-north-4.myhuaweicloud.com/v2.0/ivs-standardContent-Type: application/jsonx-auth-token: MIIaBgYJKoZIhvcNAQcC……

状态码 HTTP 状态码为三位数，分成五个类别：1xx：相关信息；2xx：操作成功；3xx：重定向；4xx：客户端错误；5xx：服务器错误。 状态码如下所示。 状态码 编码 状态说明 100 Continue 继续请求。 这个临时响应用来通知客户端，它的部分请求已经被服务器接收，且仍未被拒绝。 101 Switching Protocols 切换协议。只能切换到更高级的协议。 例如，切换到HTTPS的新版本协议。 200 OK 服务器已成功处理了请求。 201 Created 创建类的请求完全成功。 202 Accepted 已经接受请求，但未处理完成。 203 Non-Authoritative Information 非授权信息，请求成功。 204 No Content 请求完全成功，同时HTTP响应不包含响应体。 在响应OPTIONS方法的HTTP请求时返回此状态码。 205 Reset Content 重置内容，服务器处理成功。 206 Partial Content 服务器成功处理了部分GET请求。 300 Multiple Choices 多种选择。请求的资源可包括多个位置，相应可返回一个资源特征与地址的列表用于用户终端（例如：浏览器）选择。 301 Moved Permanently 永久移动，请求的资源已被永久的移动到新的URI，返回信息会包括新的URI。 302 Found 资源被临时移动。 303 See Other 查看其它地址，使用GET和POST请求查看。 304 Not Modified 所请求的资源未修改，服务器返回此状态码时，不会返回任何资源。 305 Use Proxy 所请求的资源必须通过代理访问。 306 Unused 已经被废弃的HTTP状态码。 400 Bad Request 非法请求。 建议直接修改该请求，不要重试该请求。 401 Unauthorized 在客户端提供认证信息后，返回该状态码，表明服务端指出客户端所提供的认证信息不正确或非法。 402 Payment Required 保留请求。 403 Forbidden 请求被拒绝访问。 返回该状态码，表明请求能够到达服务端，且服务端能够理解用户请求，但是拒绝做更多的事情，因为该请求被设置为拒绝访问，建议直接修改该请求，不要重试该请求。 404 Not Found 所请求的资源不存在。 建议直接修改该请求，不要重试该请求。 405 Method Not Allowed 请求中带有该资源不支持的方法。 建议直接修改该请求，不要重试该请求。 406 Not Acceptable 服务器无法根据客户端请求的内容特性完成请求。 407 Proxy Authentication Required 请求要求代理的身份认证，与401类似，但请求者应当使用代理进行授权。 408 Request Timeout 服务器等候请求时发生超时。 客户端可以随时再次提交该请求而无需进行任何更改。 409 Conflict 服务器在完成请求时发生冲突。 返回该状态码，表明客户端尝试创建的资源已经存在，或者由于冲突请求的更新操作不能被完成。 410 Gone 客户端请求的资源已经不存在。 返回该状态码，表明请求的资源已被永久删除。 411 Length Required 服务器无法处理客户端发送的不带Content-Length的请求信息。 412 Precondition Failed 未满足前提条件，服务器未满足请求者在请求中设置的其中一个前提条件。 413 Request Entity Too Large 由于请求的实体过大，服务器无法处理，因此拒绝请求。为防止客户端的连续请求，服务器可能会关闭连接。如果只是服务器暂时无法处理，则会包含一个Retry-After的响应信息。 414 Request URI Too Long 请求的URI过长（URI通常为网址），服务器无法处理。 415 Unsupported Media Type 服务器无法处理请求附带的媒体格式。 416 Requested Range Not Satisfiable 客户端请求的范围无效。 417 Expectation Failed 服务器无法满足Expect的请求头信息。 422 Unprocessable Entity 请求格式正确，但是由于含有语义错误，无法响应。 429 Too Many Requests 表明请求超出了客户端访问频率的限制或者服务端接收到多于它能处理的请求。建议客户端读取相应的Retry-After首部，然后等待该首部指出的时间后再重试。 500 Internal Server Error 表明服务端能被请求访问到，但是不能理解用户的请求。 501 Not Implemented 服务器不支持请求的功能，无法完成请求。 502 Bad Gateway 充当网关或代理的服务器，从远端服务器接收到了一个无效的请求。 503 Service Unavailable 被请求的服务无效。 建议直接修改该请求，不要重试该请求。 504 Gateway Timeout 请求在给定的时间内无法完成。客户端仅在为请求指定超时（Timeout）参数时会得到该响应。 505 HTTP Version Not Supported 服务器不支持请求的HTTPS协议的版本，无法完成处理。 父主题： 附录

响应参数 状态码： 200 表6 响应Body参数 参数 参数类型 描述 meta Meta object 请求元数据，例如表征本次请求的唯一标注uuid。 result result object 调用返回结果。 表7 Meta 参数 参数类型 描述 uuid String 唯一标识此次请求的ID，用户自定义，不超过64位。 表8 result 参数 参数类型 描述 service_name String 子服务名称。 count Integer 执行检测的数量，与resp_data字段对应。 resp_data Array of StandardRespDataByVideoAndNameAndId objects 请求列表，用于支持批量调用。目前暂时只支持单个数据查询。 表9 StandardRespDataByVideoAndNameAndId 参数 参数类型 描述 verification_result String 审核校验结果： "valid"表示身份审核通过； "invalid"表示身份审核不通过； "nonexistent"表示数据源没有该身份证号码，这种情况一般是被验证人正在办理户籍迁移，或者被验证人是军人或政要。 verification_message String 审核校验信息，具体参考校验信息说明 verification_code Integer 审核校验代码，具体参考校验信息说明 similarity String 人像相识度。取值范围[0,100]，当入参detail为true时，取值范围为[0,1000]。 video_result VideoResult object 动作活体检测的检测结果。 表10 VideoResult 参数 参数类型 描述 alive Boolean 是否是活体。 actions Array of ActionsList objects 动作列表。 picture String 检测出最大人脸的图片base64。 表11 ActionsList 参数 参数类型 描述 confidence Double 置信度，取值范围0～1。 action Integer 动作编号，取值范围：[1,2,3,4]，其中： 1：左摇头 2：右摇头 3：点头 4：嘴部动作 状态码： 400 表12 响应Body参数 参数 参数类型 描述 error_code String 调用失败时的错误码，具体请参考错误码。 调用成功时无此字段。 error_msg String 调用失败时的错误信息。 调用成功时无此字段。

请求示例 使用身份证姓名、号码、人脸视频进行活体人证核验 POST https://{endpoint}/v2.0/ivs-standard{ "meta" : { "uuid" : "user_defined" }, "data" : { "req_data" : [ { "verification_name" : "张三", "verification_id" : "44***********07", "video" : "/9j/4AAQSkZJRgABAgEASABIAAD...", "actions" : "1,3,2", "nod_threshold" : 10 } ] }}

响应示例 状态码： 200 OK { "meta" : { "uuid" : "user_defined" }, "result" : { "service_name" : "ivs-standard", "count" : 1, "resp_data" : [ { "verification_result" : "valid", "verification_message" : "Successful certification", "verification_code" : 1000, "similarity" : "65", "video_result" : { "alive" : true, "actions" : [ { "confidence" : 0.823, "action" : 1 }, { "confidence" : 0.823, "action" : 3 }, { "confidence" : 0.823, "action" : 2 } ], "picture" : "/9j/4AAQSkZJRgABAQEAYABgAAD/2w..." } } ] }} 状态码： 400 失败响应样例 { "error_code" : "IVS.0003", "error_msg" : "Some necessary request parameters in req_data is null."}

请求参数 表1 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String X-Auth-Token值获取方法请参见认证鉴权。 Enterprise-Project-Id 否 String 企业项目ID。IVS支持通过企业项目管理（EPS）对不同用户组和用户的资源使用，进行分账。 获取方法：进入“企业项目管理”页面，单击企业项目名称，在企业项目详情页获取Enterprise-Project-Id（企业项目ID）。 企业项目创建步骤请参见用户指南。 说明： 说明： 创建企业项目后，在传参时，有以下三类场景。 携带正确的ID，正常使用IVS服务，账单的企业项目会被分类到企业ID对应的企业项目中。 携带格式正确但不存在的ID，正常使用IVS服务，账单的企业项目会显示对应不存在的企业项目ID。 不携带ID或格式错误ID（包含特殊字符等），正常使用IVS服务，账单的企业项目会被分类到"default"中。 表2 请求Body参数 参数 是否必选 参数类型 描述 meta 是 Meta object 请求元数据，例如表征本次请求的唯一标注uuid。 data 是 data object 请求消息的数据部分。 表3 Meta 参数 是否必选 参数类型 描述 uuid 否 String 唯一标识此次请求的ID，用户自定义，不超过64位。 表4 data 参数 是否必选 参数类型 描述 req_data 否 Array of StandardReqDataByVideoAndNameAndId objects 请求列表，用于支持批量调用。目前暂时只支持单个数据查询。 表5 StandardReqDataByVideoAndNameAndId 参数 是否必选 参数类型 描述 verification_name 是 String 被验证人的姓名。 verification_id 是 String 被验证人的身份证号码。 video 是 String 现场拍摄人像视频数据，使用base64编码。 视频文件大小不超过8MB，建议客户端压缩到200KB~2MB。要求base64编码后大小不超过10M。 限制视频时长1～15秒。 建议帧率10fps～30fps。 封装格式：mp4、avi、flv、webm、asf、mov。 视频编码格式：h261、h263、h264、hevc、vc1、vp8、vp9、wmv3。 actions 是 String 动作代码顺序列表，英文逗号（,）分隔。建议单动作，目前支持的动作有： 1：左摇头 2：右摇头 3：点头 4：嘴部动作 嘴部动作建议嘴唇距离大于3厘米，左右摇头动作建议角度15-30度。 nod_threshold 否 Double 该参数为点头动作幅度的判断门限，取值范围：[1,90]，默认为10，单位为度。该值设置越大，则越难判断为点头。 detail 否 Boolean 响应参数similarity是否详细显示,默认为false。 true表示响应中的similarity为0~1000的小数。 false表示响应中的similarity为0~100的整数。

响应参数 状态码： 200 表6 响应Body参数 参数 参数类型 描述 meta Meta object 请求元数据，例如表征本次请求的唯一标注uuid。 result result object 调用返回结果。 表7 Meta 参数 参数类型 描述 uuid String 唯一标识此次请求的ID，用户自定义，不超过64位。 表8 result 参数 参数类型 描述 service_name String 子服务名称。 count Integer 执行检测的数量，与resp_data字段对应。 resp_data Array of RespDataByVideoAndIdCardImage objects 请求列表，用于支持批量调用。目前暂时只支持单个数据查询。 表9 RespDataByVideoAndIdCardImage 参数 参数类型 描述 verification_result String 审核校验结果： "valid"表示身份审核通过； "invalid"表示身份审核不通过； "nonexistent"表示数据源没有该身份证号码，这种情况一般是被验证人正在办理户籍迁移，或者被验证人是军人或政要。 verification_message String 审核校验信息，具体参考校验信息说明 verification_code Integer 审核校验代码，具体参考校验信息说明 similarity String 人像相识度。取值范围[0,100]，当入参detail为true时，取值范围为[0,1000]。 idcard_result IdcardResult object 身份证图像的 文字识别 结果，具体参见IdcardResult。 video_result VideoResult object 动作活体检测的检测结果。 表10 IdcardResult 参数 参数类型 描述 name String 身份证上识别的名称。 number String 身份证号。 sex String 性别。 birth String 出生日期。 ethnicity String 民族。 address String 地址。 issue String 发证机关。 valid_from String 有效起始日期。 valid_to String 有效结束日期。 表11 VideoResult 参数 参数类型 描述 alive Boolean 是否是活体。 actions Array of ActionsList objects 动作列表。 picture String 检测出最大人脸的图片base64。 表12 ActionsList 参数 参数类型 描述 confidence Double 置信度，取值范围0～1。 action Integer 动作编号，取值范围：[1,2,3,4]，其中： 1：左摇头 2：右摇头 3：点头 4：嘴部动作 状态码： 400 表13 响应Body参数 参数 参数类型 描述 error_code String 调用失败时的错误码，具体请参考错误码。 调用成功时无此字段。 error_msg String 调用失败时的错误信息。 调用成功时无此字段。

请求示例 使用身份证正、反面图片、人脸视频进行活体人证核验 POST https://{endpoint}/v2.0/ivs-standard{ "meta" : { "uuid" : "user_defined" }, "data" : { "req_data" : [ { "idcard_image1" : "/9j/4AAQSkZJRgABAgEASA...", "idcard_image2" : "/9j/4AAAAABQSkZJRgABAg...", "video" : "/9j/4AAQSkZJRgABAgEASABIAAD...", "actions" : "1,3,2", "nod_threshold" : 10 } ] }}

响应示例 状态码： 200 OK { "meta" : { "uuid" : "user_defined" }, "result" : { "service_name" : "ivs-standard", "count" : 1, "resp_data" : [ { "verification_result" : "valid", "verification_message" : "Successful certification", "verification_code" : 1000, "similarity" : "65", "idcard_result" : { "name" : "张三", "sex" : "男", "birth" : "2000-03-06", "ethnicity" : "汉", "address" : "XX省XX市XX区XX街道XX号", "number" : "44***********07", "issue" : "XX省XX市XX区XX派出所", "valid_from" : "2004-08-26", "valid_to" : "2034-08-26" }, "video_result" : { "alive" : true, "actions" : [ { "confidence" : 0.823, "action" : 1 }, { "confidence" : 0.823, "action" : 3 }, { "confidence" : 0.823, "action" : 2 } ], "picture" : "/9j/4AAQSkZJRgABAQEAYABgAAD/2w..." } } ] }} 状态码： 400 失败响应样例 { "error_code" : "IVS.0003", "error_msg" : "Some necessary request parameters in req_data is null."}

请求参数 表1 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String X-Auth-Token值获取方法请参见认证鉴权。 Enterprise-Project-Id 否 String 企业项目ID。IVS支持通过企业项目管理（EPS）对不同用户组和用户的资源使用，进行分账。 获取方法：进入“企业项目管理”页面，单击企业项目名称，在企业项目详情页获取Enterprise-Project-Id（企业项目ID）。 企业项目创建步骤请参见用户指南。 说明： 说明： 创建企业项目后，在传参时，有以下三类场景。 携带正确的ID，正常使用IVS服务，账单的企业项目会被分类到企业ID对应的企业项目中。 携带格式正确但不存在的ID，正常使用IVS服务，账单的企业项目会显示对应不存在的企业项目ID。 不携带ID或格式错误ID（包含特殊字符等），正常使用IVS服务，账单的企业项目会被分类到"default"中。 表2 请求Body参数 参数 是否必选 参数类型 描述 meta 是 Meta object 请求元数据，例如表征本次请求的唯一标注uuid。 data 是 data object 请求消息的数据部分。 表3 Meta 参数 是否必选 参数类型 描述 uuid 否 String 唯一标识此次请求的ID，用户自定义，不超过64位。 表4 data 参数 是否必选 参数类型 描述 req_data 否 Array of ReqDataByVideoAndIdCardImage objects 请求列表，用于支持批量调用。目前暂时只支持单个数据查询。 表5 ReqDataByVideoAndIdCardImage 参数 是否必选 参数类型 描述 idcard_image1 是 String 身份证人像面图像数据，使用base64编码，要求base64编码后大小不超过4M。图像各边的像素大小在300到4000之间，支持JPG格式。 idcard_image2 否 String 身份证国徽面图像数据，使用base64编码，要求base64编码后大小不超过4M。图像各边的像素大小在300到4000之间，支持JPG格式。 video 是 String 现场拍摄人像视频数据，使用base64编码。 视频文件大小不超过8MB，建议客户端压缩到200KB~2MB。要求base64编码后大小不超过10M。 限制视频时长1～15秒。 建议帧率10fps～30fps。 封装格式：mp4、avi、flv、webm、asf、mov。 视频编码格式：h261、h263、h264、hevc、vc1、vp8、vp9、wmv3。 actions 是 String 动作代码顺序列表，英文逗号（,）分隔。建议单动作，目前支持的动作有： 1：左摇头 2：右摇头 3：点头 4：嘴部动作 嘴部动作建议嘴唇距离大于3厘米，左右摇头动作建议角度15-30度。 nod_threshold 否 Double 该参数为点头动作幅度的判断门限，取值范围：[1,90]，默认为10，单位为度。该值设置越大，则越难判断为点头。 detail 否 Boolean 响应参数similarity是否详细显示,默认为false。 true表示响应中的similarity为0~1000的小数。 false表示响应中的similarity为0~100的整数。

Token认证 需要使用一个Token鉴权时，可以先缓存起来，避免频繁调用。 关于Token有效期的详细说明请参见获取 IAM 用户Token（使用密码）。 如果您的华为云账号已升级为华为账号，将不支持获取账号Token。建议为您自己创建一个IAM用户，获取IAM用户的Token。详细说明请参见账密报错。 Token在计算机系统中代表令牌（临时）的意思，拥有Token就代表拥有某种权限。Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限。 username为用户名，domainname为用户所属的账号名称，********为用户登录密码，project name为项目名称。username，domainname和project name的获取方法参见获取用户名、用户ID、项目名称、项目ID。 获取Token 的终端节点和project name需与IVS服务终端节点保持一致。当访问华北-北京四的终端节点（即访问https://ivs.cn-north-4.myhuaweicloud.com时），获取Token请使用终端节点https://iam.cn-north-4.myhuaweicloud.com，project name为cn-north-4。 POST https://iam.cn-north-4.myhuaweicloud.com/v3/auth/tokensContent-Type: application/jsonRequest Body:{ "auth": { "identity": { "methods": [ "password" ], "password": { "user": { "name": "username", //替换为实际用户名 "password": "********", //替换为实际的用户密码 "domain": { "name": "domainname" //替换为实际账号名 } } } }, "scope": { "project": { "name": "project name" //替换为实际的project name，如cn-north-4 } } } } 如下图所示，返回的响应消息头中“x-subject-token”就是需要获取的用户Token。获取Token之后，您就可以使用Token认证调用IVS服务API。

响应消息体 响应消息体通常以结构化格式返回，与响应消息头中Content-type对应，传递除响应消息头之外的内容。 对于人证核身标准版（三要素）接口，返回如下消息体。 { "meta": { "uuid": "user_defined" }, "result": { "service_name": "ivs-standard", "count": 1, "resp_data": [ { "verification_result": "valid", "verification_message": "Successful certification", "verification_code": 1000, "similarity": "88.43", "idcard_result": { "name": "张三", "sex": "男", "birth": "2000-03-06", "ethnicity": "汉", "address": "XX省XX市XX区XX街道XX号", "number": "610XXXXXXXXXXXXXXX" } } ] }} 当接口调用出错时，会返回错误码及错误信息说明，错误响应的Body体格式如下所示。 { "error_code": "IVS.0003", "error_msg": "Some necessary request parameters in req_data is null."} 其中，error_code表示错误码，error_msg表示错误描述信息。

申请服务 正式使用服务之前，必须先申请开通服务，下面是相关服务申请的步骤。 首次使用服务时，需要先申请开通该服务。服务只需要开通一次即可，后面使用时无需再次申请。如未开通服务，调用服务时会提示IVS.0015报错，请在调用服务前先进入控制台开通服务，并注意开通服务区域与调用服务的区域保持一致。 登录人证核身服务控制台。 选择需要使用的服务，在操作列单击“开通服务”。 图1 开通服务 服务开通成功后，开通状态显示“已开通”。 父主题： 如何调用API

请求示例 使用身份证正、反面图片进行身份核验 POST https://{endpoint}/v2.0/ivs-idcard-extention{ "meta" : { "uuid" : "user_defined" }, "data" : { "req_data" : [ { "idcard_image1" : "/9j/4BBQSkZJRgABAgEASB...", "idcard_image2" : "/9j/4BBQSkZJRgABAgEASB..." } ] }}

响应参数 状态码： 200 表6 响应Body参数 参数 参数类型 描述 meta Meta object 请求元数据，例如表征本次请求的唯一标注uuid。 result result object 调用返回结果。 表7 Meta 参数 参数类型 描述 uuid String 唯一标识此次请求的ID，用户自定义，不超过64位。 表8 result 参数 参数类型 描述 service_name String 子服务名称。 count Integer 执行检测的数量，与resp_data字段对应。 resp_data Array of ExtentionRespDataByIdCardImage objects 请求列表，用于支持批量调用。目前暂时只支持单个数据查询。 表9 ExtentionRespDataByIdCardImage 参数 参数类型 描述 verification_result String 审核校验结果： "valid"表示身份审核通过； "invalid"表示身份审核不通过； "nonexistent"表示数据源没有该身份证号码，这种情况一般是被验证人正在办理户籍迁移，或者被验证人是军人或政要。 verification_message String 审核校验信息，具体参考校验信息说明 verification_code Integer 审核校验代码，具体参考校验信息说明 idcard_result IdcardResult object 身份证图像的文字识别结果，具体参见IdcardResult。 表10 IdcardResult 参数 参数类型 描述 name String 身份证上识别的名称。 number String 身份证号。 sex String 性别。 birth String 出生日期。 ethnicity String 民族。 address String 地址。 issue String 发证机关。 valid_from String 有效起始日期。 valid_to String 有效结束日期。 状态码： 400 表11 响应Body参数 参数 参数类型 描述 error_code String 调用失败时的错误码，具体请参考错误码。 调用成功时无此字段。 error_msg String 调用失败时的错误信息。 调用成功时无此字段。

响应示例 状态码： 200 OK { "meta" : { "uuid" : "user_defined" }, "result" : { "service_name" : "ivs-idcard-extention", "count" : 1, "resp_data" : [ { "verification_result" : "valid", "verification_message" : "Successful certification", "verification_code" : 1000, "idcard_result" : { "name" : "张三", "sex" : "男", "birth" : "2000-03-06", "ethnicity" : "汉", "address" : "XX省XX市XX区XX街道XX号", "number" : "44***********07", "issue" : "XX省XX市XX区XX派出所", "valid_from" : "2004-08-26", "valid_to" : "2034-08-26" } } ] }} 状态码： 400 失败响应样例 { "error_code" : "IVS.0003", "error_msg" : "Some necessary request parameters in req_data is null."}

请求参数 表1 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String X-Auth-Token值获取方法请参见认证鉴权。 Enterprise-Project-Id 否 String 企业项目ID。IVS支持通过企业项目管理（EPS）对不同用户组和用户的资源使用，进行分账。 获取方法：进入“企业项目管理”页面，单击企业项目名称，在企业项目详情页获取Enterprise-Project-Id（企业项目ID）。 企业项目创建步骤请参见用户指南。 说明： 说明： 创建企业项目后，在传参时，有以下三类场景。 携带正确的ID，正常使用IVS服务，账单的企业项目会被分类到企业ID对应的企业项目中。 携带格式正确但不存在的ID，正常使用IVS服务，账单的企业项目会显示对应不存在的企业项目ID。 不携带ID或格式错误ID（包含特殊字符等），正常使用IVS服务，账单的企业项目会被分类到"default"中。 表2 请求Body参数 参数 是否必选 参数类型 描述 meta 是 Meta object 请求元数据，例如表征本次请求的唯一标注uuid。 data 是 data object 请求消息的数据部分。 表3 Meta 参数 是否必选 参数类型 描述 uuid 否 String 唯一标识此次请求的ID，用户自定义，不超过64位。 表4 data 参数 是否必选 参数类型 描述 req_data 否 Array of ExtentionReqDataByIdCardImage objects 请求列表，用于支持批量调用。目前暂时只支持单个数据查询。 表5 ExtentionReqDataByIdCardImage 参数 是否必选 参数类型 描述 idcard_image1 是 String 身份证人像面图像数据，使用base64编码，要求base64编码后大小不超过4M。图像各边的像素大小在300到4000之间，支持JPG格式。 idcard_image2 否 String 身份证国徽面图像数据，使用base64编码，要求base64编码后大小不超过4M。图像各边的像素大小在300到4000之间，支持JPG格式。

基本概念 账号 用户注册华为云时的账号，账号对其所拥有的资源及云服务具有完全的访问权限，可以重置用户密码、分配用户权限等。由于账号是付费主体，为了确保账号安全，建议您不要直接使用账号进行日常管理工作，而是创建用户并使用他们进行日常管理工作。 用户 由账号在IAM中创建的用户，是云服务的使用人员，具有身份凭证（密码和访问密钥）。 在我的凭证页面，您可以查看账号ID和用户ID。通常在调用API的鉴权过程中，您需要用到账号、用户和密码等信息。 区域（Region） 从地理位置和网络时延维度划分，同一个Region内共享弹性计算、块存储、对象存储、VPC网络、弹性公网IP、镜像等公共服务。Region分为通用Region和专属Region，通用Region指面向公共租户提供通用云服务的Region；专属Region指只承载同一类业务或只面向特定租户提供业务服务的专用Region。 详情请参见区域和可用区。 可用区（AZ，Availability Zone） 一个AZ是一个或多个物理数据中心的集合，有独立的风火水电，AZ内逻辑上再将计算、网络、存储等资源划分成多个集群。一个Region中的多个AZ间通过高速光纤相连，以满足用户跨AZ构建高可用性系统的需求。 项目 华为云的区域默认对应一个项目，这个项目由系统预置，用来隔离物理区域间的资源（计算资源、存储资源和网络资源），以默认项目为单位进行授权，用户可以访问您账号中该区域的所有资源。如果您希望进行更加精细的权限控制，可以在区域默认的项目中创建子项目，并在子项目中购买资源，然后以子项目为单位进行授权，使得用户仅能访问特定子项目中资源，使得资源的权限控制更加精确。 图1 项目隔离模型 父主题： 使用前必读

IdcardResult 身份证 图像文字识别 结果结构体。 表1 结构体说明 参数 类型 描述 name String 身份证上识别的名称。 number String 身份证号。 sex String 性别。 birth String 出生日期。 ethnicity String 民族。 address String 地址。 issue String 发证机关。 valid_from String 有效起始日期。 valid_to String 有效结束日期。 表2 VideoResult 参数 参数类型 描述 alive Boolean 是否是活体。 actions Array of ActionsList objects 动作列表。 picture String 检测出最大人脸的图片base64。 表3 ActionsList 参数 参数类型 描述 confidence Double 置信度，取值范围0～1。 action Integer 动作编号，取值范围：[1,2,3,4]，其中： 1：左摇头 2：右摇头 3：点头 4：嘴部动作 父主题： 公共数据结构

约束与限制 只支持“华北-北京四”区域。 只支持中国大陆身份证的识别。 只支持JPG格式，图片中人像需无遮挡。 图像数据，base64编码，要求base64编码后大小不超过4MB。 图像各边的像素大小在300到8000px之间。 图像中身份证区域有效占比超过15%，保证整张身份证内容及其边缘包含在图像内。 支持图像中身份证要求水平放置。 目前支持检测视频文件，或视频的Base64编码，不支持直接检测视频流，需要用户客户端自己获取视频流并保存成文件，然后调用活体检测接口。 视频文件大小不超过8MB，建议客户端压缩到200KB~2MB。 限制视频时长1～15秒。 建议帧率10fps～30fps。 封装格式：mp4、avi、flv、webm、asf、mov。 视频编码格式：h261、h263、h264、hevc、vc1、vp8、vp9、wmv3。 父主题： 使用前必读

生僻字识别不成功说明 由于历史原因，公安部门在办理身份证登记身份信息时，使用了微软或其他输入法，将生僻字以PUA编码形式记录在了公安数据库中。随着信息化发展，这些生僻字以新的编码被国家标准GB18030收录。如今，在手机及通用计算机上都是使用新的编码输入和显示这些生僻字，但由于实名认证时公安系统是根据汉字编码进行比较，而这些生僻字PUA编码和GB18030编码并不一致，所以核验不会通过。 解决方案： 通过第三方网站提供的生僻字查询功能，传入生僻字以其他方式编码的姓名进行核验（https://name.vurls.cn/ui/index/uigen/）。 以更正信息为由到公安机关申请换证，以新的通用编码重新录入姓名。

终端节点 终端节点即调用API的请求地址，不同服务不同区域的终端节点不同，您可以从地区和终端节点中查询所有服务的终端节点。 人证核身的终端节点如表1所示，请您根据业务需要选择对应区域的终端节点。 表1 人证核身的终端节点 区 域名 称 区域 终端节点（Endpoint） 部署服务 华北-北京四 cn-north-4 ivs.cn-north-4.myhuaweicloud.com 标准版（三要素）、证件版（二要素） 父主题： 使用前必读

错误码说明 表1 错误码 状态码 错误码 错误信息 说明 处理措施 400 IVS.0001 Request parameter meta is null or empty. 请求体参数为null或空。 请参考API文档填写请求Body信息，并检查请求body格式是否正确。 400 IVS.0002 Request parameter req_data is redundant. 请求体参数冗余，req_data的元素数量大于1。 req_data列表中当前仅支持1个元素。 400 IVS.0003 Some necessary request parameters in req_data is null. 请求参数有一些必要的参数为null。 请参考API文档填写必要的参数后重试。 400 IVS.0004 Image base64 size is more than 4MB or less than 10KB. 图像的base64数据量大于4MB或小于10KB。 要求base64编码后大小不超过4MB。图像各边的像素大小在300到8000px之间。 400 IVS.0005 Video base 64 size is more than 10MB or less than 10KB. 视频的base 64数据量大于10MB或小于10KB。 要求base 64编码后大小不超过10MB。建议客户端压缩至200KB至2MB。 400 IVS.0006 The input face image is invalid. 输入的人脸图像不合法。 要求base64编码后大小不超过4MB。图像各边的像素大小在300到4000px之间，支持JPG格式。 400 IVS.0007 Id card image error: %s. Please try another image. 输入的身份证图像错误，请换张图像重试。 请检查身份证图片是否正常，图片中文字清晰，并根据具体错误信息更换图片。 400 IVS.0008 live detect error: %s. Please check your input. 活体检测失败，请检查输入。 请检查视频是否正常，视频中的人的头部和脸部符合动作要求，并根据具体错误信息更换视频或修改动作列表。 400 IVS.0009 face detect error: %s. Please check your input. 人脸检测失败，请检查输入。 请检查人脸图片是否正常，图片中有清晰的人脸，并根据具体错误信息更换图片。 400 IVS.0010 face compare error: %s. Please check your input. 人脸比对失败，请检查输入。 请检查输入图片base64中是否包含人脸。 400 IVS.0011 The request param has wrong format, the length of %s exceeds %s bytes. The request param has wrong format, error in parsing %s, %s type expected. The request param has wrong format, %s is null or empty. The request param has wrong format, verification_name contain invalid characters. The request param has wrong format, verification_id length must equal 15 or 18. The request param has wrong format, verification_id is invalid. 请求参数格式错误，参数长度超出范围。 请求参数格式错误，解析参数出现错误。 请求参数格式错误，参数的值为null或空。 请求参数格式错误，verification_name 包含了无效字符。 请求参数格式错误，verification_id长度需为15位或18位。 请求参数格式错误，verification_id无效。 请将参数长度设置在相应范围内。 请参考API文档，修改对应参数的类型。 请检查参数名是否填写正确，以及参数名对应的值是否有填写。 请检查verification_name是否为有效的姓名。 请检查verification_id的长度。 请检查verification_id是否为有效的身份证号码。 400 IVS.0012 Lack Header or Header Content-Type is empty. 缺少请求头或请求头为空。 请参考API文档填写请求头。 400 IVS.0013 The authentication token is abnormal. Token异常。 请参考认证鉴权重新获取Token。 400 IVS.0014 The service has been frozen. 服务已冻结。 请检查是否有欠费。 400 IVS.0015 The subservice has not been subscribed. 服务未开通。 请登录控制台开通人证核身服务。 已开通情况下，检查服务的开通区域和调用API时，url中填写的区域是否一致。 500 IVS.0101 Service inner error. 服务内部错误。 请联系华为云支持人员。 当您调用API时，如果遇到“APIGW”,“APIG”开头的错误码，请参见API网关错误码进行处理。

响应示例 状态码： 200 OK { "meta" : { "uuid" : "user_defined" }, "result" : { "service_name" : "ivs-idcard-extention", "count" : 1, "resp_data" : [ { "verification_result" : "valid", "verification_message" : "Successful certification", "verification_code" : 1000 } ] }} 状态码： 400 失败响应样例 { "error_code" : "IVS.0003", "error_msg" : "Some necessary request parameters in req_data is null."}

响应参数 状态码： 200 表6 响应Body参数 参数 参数类型 描述 meta Meta object 请求元数据，例如表征本次请求的唯一标注uuid。 result result object 调用返回结果。 表7 Meta 参数 参数类型 描述 uuid String 唯一标识此次请求的ID，用户自定义，不超过64位。 表8 result 参数 参数类型 描述 service_name String 子服务名称。 count Integer 执行检测的数量，与resp_data字段对应。 resp_data Array of ExtentionRespDataByNameAndId objects 请求列表，用于支持批量调用。目前暂时只支持单个数据查询。 表9 ExtentionRespDataByNameAndId 参数 参数类型 描述 verification_result String 审核校验结果： "valid"表示身份审核通过； "invalid"表示身份审核不通过； "nonexistent"表示数据源没有该身份证号码，这种情况一般是被验证人正在办理户籍迁移，或者被验证人是军人或政要。 verification_message String 审核校验信息，具体参考校验信息说明 verification_code Integer 审核校验代码，具体参考校验信息说明 状态码： 400 表10 响应Body参数 参数 参数类型 描述 error_code String 调用失败时的错误码，具体请参考错误码。 调用成功时无此字段。 error_msg String 调用失败时的错误信息。 调用成功时无此字段。

请求示例 使用身份证姓名、号码进行身份核验 POST https://{endpoint}/v2.0/ivs-idcard-extention{ "meta" : { "uuid" : "user_defined" }, "data" : { "req_data" : [ { "verification_name" : "张三", "verification_id" : "44***********07" } ] }}

请求参数 表1 请求Header参数 参数 是否必选 参数类型 描述 X-Auth-Token 是 String X-Auth-Token值获取方法请参见认证鉴权。 Enterprise-Project-Id 否 String 企业项目ID。IVS支持通过企业项目管理（EPS）对不同用户组和用户的资源使用，进行分账。 获取方法：进入“企业项目管理”页面，单击企业项目名称，在企业项目详情页获取Enterprise-Project-Id（企业项目ID）。 企业项目创建步骤请参见用户指南。 说明： 说明： 创建企业项目后，在传参时，有以下三类场景。 携带正确的ID，正常使用IVS服务，账单的企业项目会被分类到企业ID对应的企业项目中。 携带格式正确但不存在的ID，正常使用IVS服务，账单的企业项目会显示对应不存在的企业项目ID。 不携带ID或格式错误ID（包含特殊字符等），正常使用IVS服务，账单的企业项目会被分类到"default"中。 表2 请求Body参数 参数 是否必选 参数类型 描述 meta 是 Meta object 请求元数据，例如表征本次请求的唯一标注uuid。 data 是 data object 请求消息的数据部分。 表3 Meta 参数 是否必选 参数类型 描述 uuid 否 String 唯一标识此次请求的ID，用户自定义，不超过64位。 表4 data 参数 是否必选 参数类型 描述 req_data 否 Array of ExtentionReqDataByNameAndId objects 请求列表，用于支持批量调用。目前暂时只支持单个数据查询。 表5 ExtentionReqDataByNameAndId 参数 是否必选 参数类型 描述 verification_name 是 String 被验证人的姓名。 verification_id 是 String 被验证人的身份证号码。

GSL权限 默认情况下，管理员创建的IAM用户没有任何权限，需要将其加入用户组，并给用户组授予策略或角色，才能使得用户组中的用户获得对应的权限，这一过程称为授权。授权后，用户就可以基于被授予的权限对云服务进行操作。 由于缓存的影响，对用户、用户组授予 全球SIM联接 系统策略后，需要等待10-15分钟策略才能生效。 若通过控制台使用全球SIM联接服务，请在授予系统策略后退出登录，之后重新登录继续使用。 若使用全球SIM联接的应用侧API，请在授予系统策略后，重新获取IAM用户token。

调用API获取项目ID 获取项目ID的接口为“GET https://{endpoint}/v3/projects”，其中“{endpoint}”为IAM的终端节点。接口的认证鉴权请参见认证鉴权。 响应示例如下，例如，人证核身服务部署的区域为“cn-north-4”，响应消息体中查找“name”为“cn-north-4”，其中“projects”下的“id”即为项目ID。 { "projects": [ { "domain_id": "65382450e8f64ac0870cd180d14e684b", "is_domain": false, "parent_id": "65382450e8f64ac0870cd180d14e684b", "name": "project_name", "description": "", "links": { "next": null, "previous": null, "self": "https://www.example.com/v3/projects/a4a5d4098fb4474fa22https://support-intl.huaweicloud.com/zh-cn/devg-apisign/api-sign-provide.htmlcd05f897d6b99" }, "id": "a4a5d4098fb4474fa22cd05f897d6b99", "enabled": true } ], "links": { "next": null, "previous": null, "self": "https://www.example.com/v3/projects" } }