版权声明 腾讯云版权所有本文档著作权归腾讯云单独所有, 未经腾讯云事先书面许可, 任何主体不得以任何形式复制 修改 抄袭 传播全部或部分本文档内容 商标声明 及其它腾讯云服务相关的商标均为腾讯云计算 ( 北京 ) 有限责任公司及其关联公司所有 本文档涉及的第三方主体的商标, 依法

Transcription

1 人脸识别 API 文档 产品文档 第 1 共 102 页

2 版权声明 腾讯云版权所有本文档著作权归腾讯云单独所有, 未经腾讯云事先书面许可, 任何主体不得以任何形式复制 修改 抄袭 传播全部或部分本文档内容 商标声明 及其它腾讯云服务相关的商标均为腾讯云计算 ( 北京 ) 有限责任公司及其关联公司所有 本文档涉及的第三方主体的商标, 依法由权利人所有 服务声明 本文档意在向客户介绍腾讯云全部或部分产品 服务的当时的整体概况, 部分产品 服务的内容可能有所调整 您所购买的腾讯云产品 服务的种类 服务标准等应由您与腾讯云之间的商业合同约定, 除非双方另有约定, 否则, 腾讯云对本文档内容不做任何明示或模式的承诺或保证 第 2 共 102 页

3 文档目录 API 文档 API 概览错误码说明鉴权签名人脸检测五官定位人脸比对个体信息管理人脸验证人脸检索多脸检索人脸静态活体检测 第 3 共 102 页

4 API 文档 API 概览 最近更新时间 : :04:18 为满足广大开发者的开发需求, 腾讯云智能图像为您提供了丰富的人脸识别 API 接口 人脸识别接口 功能人脸检测五官定位人脸比对个体信息管理人脸验证人脸检索多脸检索人脸融合人脸静态活体检测 详细说明查看文档查看文档查看文档查看文档查看文档查看文档查看文档查看文档查看文档 第 4 共 102 页

5 错误码说明 最近更新时间 : :09:20 人脸错误码说明 错误码 含义 3 错误的请求 ; 其中 message:account abnormal,errorno is:2 为账号欠费停服 4 签名为空 5 签名串错误 6 签名中的 appid/bucket 与操作目标不匹配 9 签名过期 10 appid 不存在 11 secretid 不存在 12 appid 和 secretid 不匹配 13 重放攻击 14 签名校验失败 15 操作太频繁, 触发频控 16 Bucket 不存在 21 无效参数 23 请求包体过大 107 鉴权服务内部错误 108 鉴权服务不可用 213 内部错误 人脸检测失败 图片解码失败 第 5 共 102 页

6 错误码 含义 特征处理失败 提取轮廓错误 提取性别错误 提取表情错误 提取年龄错误 提取姿态错误 提取眼镜错误 特征存储错误 图片为空 参数为空 个体已存在 个体不存在 参数过长 人脸不存在 组不存在 组列表不存在 url 图片下载失败 人脸个数超过限制 个体个数超过限制 组个数超过限制 对个体添加了几乎相同的人脸 非法的图片格式 图片下载失败 第 6 共 102 页

7 图片鉴黄错误码说明 错误码 含义 3 错误的请求 ; 其中 message:account abnormal,errorno is:2 为账号欠费停服 4 签名为空 5 签名串错误 6 appid/bucket/url 不匹配 7 签名编码失败 ( 内部错误 ) 8 签名解码失败 ( 内部错误 ) 9 签名过期 10 appid 不存在 11 secretid 不存在 12 appid 不匹配 13 重放攻击 14 签名失败 15 操作太频繁, 触发频控 16 内部错误 17 未知错误 200 内部打包失败 201 内部解包失败 202 内部链接失败 203 内部处理超时 图片为空 url 图片下载失败 非法的图片格式 第 7 共 102 页

8 错误码 含义 图片下载失败 图片无法识别 url 格式不对 图片下载超时 无法访问 url 对应的图片服务器 url 对应的图片已被标注为不良图片, 无法访问 ( 专指存储于腾讯云的图片 ) OCR 识别错误码说明 错误码 含义 3 错误的请求 ; 其中 message:account abnormal,errorno is:2 为账号欠费停服 4 签名为空 5 签名串错误 6 appid/bucket/url 不匹配 7 签名编码失败 ( 内部错误 ) 8 签名解码失败 ( 内部错误 ) 9 签名过期 10 appid 不存在 11 secretid 不存在 12 appid 不匹配 13 重放攻击 14 签名失败 15 操作太频繁, 触发频控 16 Bucket 不存在 第 8 共 102 页

9 错误码 含义 17 url 为空 18 没有图片或 url 19 图片数过多, 单次请求最多支持 20 个 url 或文件 20 图片过大, 单个文件最大支持 1MB 21 无效的参数 200 内部打包失败 201 内部解包失败 202 内部链接失败 203 内部处理超时 图片解码失败 图片为空 请求的参数为空 url 图片下载失败 非法的图片格式 图片下载失败 图片无法识别 url 格式不对 图片下载超时 无法访问 url 对应的图片服务器 url 对应的图片已被标注为不良图片, 无法访问 ( 专指存储于腾讯云的图片 ) OCR 识别失败 提供的图片不是身份证 人脸核身错误码说明 第 9 共 102 页

10 错误码 含义 3 错误的请求 ; 其中 message:account abnormal,errorno is:2 为账号欠费停服 4 签名为空 5 签名串错误 6 签名中的 appid/bucket 与操作目标不匹配 9 签名过期 10 appid 不存在 11 secretid 不存在 12 appid 和 secretid 不匹配 13 重放攻击 14 签名校验失败 15 操作太频繁, 触发频控 16 Bucket 不存在 21 无效参数 23 请求包体过大 24 无权限, 未申请服务 107 鉴权服务不可用 108 鉴权服务不可用 213 内部错误 视频中自拍照特征提取失败 视频中自拍照之间对比失败 Card 照片提取特征失败 自拍照与 Card 照片相似度计算失败 照片解码失败 照片人脸检测失败 第 10 共 102 页

11 错误码 含义 自拍照人脸检测失败 自拍照解码失败 Card 照片人脸检测失败 Card 照片解码失败 视频无效, 上传文件不符合视频要求 唇语失败 自拍照解析照片不足, 视频里检测到的人脸较少 视频没有声音 语音识别失败, 视频里的人读错数字 视频人脸检测失败, 没有嘴或者脸 唇动检测失败, 视频里的人嘴巴未张开或者张开幅度小 活体检测失败 ( 活体其他错误都归类到里面 ) 视频中噪声太大 视频里的声音太小 活体检测 level 参数无效 视频像素太低, 最小 270* 视频里的人不是活体 ( 翻拍等攻击 ) 请求缺少身份证号码或身份证姓名 服务器内部错误, 服务暂时不可用 身份证姓名与身份证号码不一致 身份证号码无效 用户未输入图像或者 url 下载失败 图片处理 第 11 共 102 页

12 错误码 含义 参数错误 签名格式错误 后端网络错误 HTTP 请求方法错误 文件大小错误 url 参数解析不匹配 multipart/formdata 参数错误 请求参数错误 分片过大 找不到 filecontent 上传失败 cgi 初始化错误 wup 编码失败 wup 解码失败 获取路由失败 sha1 不匹配 错误的 session 建立连接错误 建立连接错误 图片下载错误码说明 图片下载失败时, 返回包 headers 中的 X-ErrNo 字段错误码说明 错误码 含义 第 12 共 102 页

13 错误码 含义 图片不存在 图片没有上传或者图片已经删除 图片涉嫌违禁 -902 镜像存储功能把请求转发到开发商源站, 但没有收到响应, 超时了 -100 未知错误, 某些场景或者逻辑未定义 -101 存储文件失败 -103 无效的请求 ; 请求报文无法识别 -104 无效的 appid Url 中包含的 appid 无效, 或者域名没有和 appid 绑定 -105 无效的样式名 Url 中指定的样式名或者别名没有配置 -106 无效的 URL Url 格式不符合格式要求 -107 无效的 Host 头域 -108 无效的 Referer -109 无效的样式名 ID 没有找到该样式名对应的图片 可能是上传该图片后, 新增的样式名, 因此图片 上传时不能生成该样式名对应的数据 -110 该图片在黑名单中 -111 http 服务器内部错误 -120 回源到源站获取数据时, 源站返回的数据有异常, 无法正常获取到图片数据 -121 http 服务器内部错误 -122 图片数据没有修改, 客户端可以使用缓存数据 -123 图片数据没有修改, 客户端可以使用缓存数据 -124 下载偏移错误 Http 请求的 Range 断点续传偏移量可能设置错误 -129 无法预料的错误 -130 http 服务器内部错误 -140 http 服务器内部错误 第 13 共 102 页

14 图片插件错误码说明 错误码 含义 服务过载 框架 handle process 错误 存储文件失败 校验 md5 失败 秒传失败 编码失败 解码失败 业务 ID 错误 图片数据异常, 压缩库无法处理 上传失败, 服务器错误 解码 biz_req 失败 编码 biz_req 失败 存储文件超时 压缩超时 校验 sha1 失败 图片 fileid 已经存在 文件缓存错误码说明 错误码 含义 -300 服务过载 -299 命令字未知 -298 解包失败 第 14 共 102 页

15 错误码 含义 -297 框架 handle process 错误 -296 打包失败 -295 文件数据异常 -294 文件数据异常 -293 通知插件失败 -292 文件缓存服务器错误 -291 编码 session 失败 -290 无效的 session -289 插件拒绝上传 -288 process 打包失败 -287 process 解包失败 -286 解码 session 失败 -285 文件过大 -284 分片大小不一致 -283 分片过小 cmd 错误码说明 错误码 含义 -199 文件移动失败 -198 重定向错误 -197 查无此文件 -196 网络请求失败 -195 网络请求失败 第 15 共 102 页

16 错误码 含义 -194 后端打包失败 -193 返回包打包失败 -192 请求包解析失败 -191 url 参数解析不匹配 -190 文件删除失败 -189 输入参数错误 :download_url empty -187 从 url 中解析参数失败 -186 暂不支持视频文件复制 -185 业务预处理失败 -184 业务后处理失败 -183 获取路由失败 -182 参数检验失败 proxy 错误码说明 错误码 含义 -99 proxy 读取配置失败 -98 调用签名服务失败 -97 非法签名 -96 签名过期 -95 消息缺少 session 信息 -94 携带错误 session 信息 -89 proxy 转发 cmd 服务失败 -88 编码 cmd 服务消息失败 第 16 共 102 页

17 错误码 含义 -87 解析 cmd 服务消息失败 -86 proxy 转发 process 服务失败 -85 解析 process 服务应答失败 -84 获取 process L5 失败 -83 签名服务解包失败 -82 不存在此 appid -81 签名为空 -80 非法的业务 ID -79 secret id 不存在 -78 SDK 协议不匹配, 请升级 -77 单次性签名已不可用 -76 单次签名没有 url -75 不支持此操作 -74 多次签名 - 过期时间为 0-73 单次签名 - 过期时间不为 0-72 签名失败 -71 操作太频繁, 请稍后再试 -70 appid/userid 与签名不匹配 -69 输入参数错误 : download_url empty -68 ip 直通车打包失败 -67 ip 直通车解包失败 -65 断点续传不支持携带数据包 -64 该业务已经被屏蔽 第 17 共 102 页

18 鉴权签名 最近更新时间 : :59:50 签名与鉴权 智能图像识别服务通过签名来验证请求的合法性 开发者将签名授权给客户端, 使其具备上传下载及管理指定资源 的能力 签名分为两种 : 多次有效签名 : 签名中绑定或者不绑定文件 fileid, 需要设置大于当前时间的有效期, 最长可设置三个月, 在此期 间内签名可多次使用 单次有效签名 : 签名中绑定文件 fileid, 有效期必须设置为 0, 此签名只可使用一次, 且只能应用于被绑定的文 件 具体应用参见签名适用场景 签名算法 获取签名所需信息 生成签名所需信息必须使用主账号的, 包括 APPID Secret ID 和 Secret Key 注意 : 如果您已使用过 API 密钥, 或在 2018 年 4 月 1 日后接入智能图像服务, 请使用 API 密钥 ; 如果您已使用过 等开头的项目 ID, 可以继续使用项目密钥, 但建议使用 API 密钥 2018 年 4 月 1 日后创建的项目 ID, 不再支持使用项目密钥 ; 目前仅支持使用主账号的 Secret ID 和 Secret Key, 暂不支持子账号的使用, 计划后续实现 拼接签名串拼接多次有效签名串 : a=[appid]&b=[bucket]&k=[secretid]&e=[expiredtime]&t=[currenttime]&r=[rand]&f=[fileid] 拼接单次有效签名串 : a=[appid]&b=[bucket]&k=[secretid]&e=[expiredtime]&t=[currenttime]&r=[rand]&f=[fileid] 第 18 共 102 页

19 注意 : 多次有效签名串中 fileid 为可选参数 ; fileid 为空, 表示不绑定资源, 例如上传签名和下载签名 ; fileid 不为空, 表示绑定资源, 例如绑定资源的下载 签名串中各字段含义如下 : 字段 a b k 解释开发者的 APPID, 接入智能图像时由系统生成 Bucket, 图片资源的组织管理单元, 历史遗留字段, 可不填 Secret ID e 签名的有效期, 是一个符合 UNIX Epoch 时间戳规范的数值, 单位为秒 ; 单次签名时,e 必须设置为 0 t r f 当前时间戳, 是一个符合 UNIX Epoch 时间戳规范的数值, 单位为秒, 多次签名时,e 应大于 t 随机串, 无符号 10 进制整数, 用户需自行生成, 最长 10 位资源存储的唯一标识, 单次签名必填 ; 多次签名选填, 如填写则会验证与当前操作的文件路径是否一致 注意 : 拼接单次有效签名串时, 有效期 e 必须设置为 0, 以保证此签名只能针对固定资源使用一次 ; 删除和复制文件必须使用单次有效签名, 上传必须使用多次有效签名 ; 具体应用参见签名适用场景 生成签名 1. 使用 HMAC-SHA1 算法对请求进行加密 (SHA1 算法加密后的输出必须是原始的二进制数据, 否则签名失败 ); 2. 对 orignal 使用 HMAC-SHA1 算法进行签名, 然后将 orignal 附加到签名结果的末尾, 再进行 Base64 编码, 得 到最终的 sign; 3. 生成签名的公式如下 : SignTmp = HMAC-SHA1(SecretKey, orignal) 第 19 共 102 页

20 Sign = Base64(SignTmp.orignal) 注意 : 此处使用的是标准的 Base64 编码, 不是 urlsafe 的 Base64 编码 ; SecretKey 为 API 密钥,orignal 为 2.2 节中拼接好的签名串 PHP 签名示例 本节介绍生成签名的算法实例, 实例中使用 PHP 语言, 如果开发者使用其他与开发, 请使用对应的算法 获取签名所需信息获取得到的签名所需信息如下 : APPID:YOUR APPID_ID Bucket:tencentyun( 可不填 ) Secret ID: YOUR SECRET_ID Secret Key: YOUR SECRET_KEY 拼接签名串 $appid = "YOUR APPID_ID"; $bucket = "tencentyun"; $secret_id = "YOUR SECRET_ID"; $secret_key = "YOUR SECRET_KEY"; $expired = time() ; $onceexpired = 0; $current = time(); $rdm = rand(); $userid = "0"; $fileid = "tencentyunsigntest"; $srcstr = 'a='.$appid.'&b='.$bucket.'&k='.$secret_id.'&e='.$expired.'&t='.$current.'&r='.$rdm.'&f='; $srcwithfile = 'a='.$appid.'&b='.$bucket.'&k='.$secret_id.'&e='.$expired.'&t='.$current.'&r='.$rdm.'& f='.$fileid; $srcstronce= 'a='.$appid.'&b='.$bucket.'&k='.$secret_id.'&e='.$onceexpired.'&t='.$current.'&r='.$rd m.'&f='.$fileid; 第 20 共 102 页

21 生成签名 SHA1 算法加密后的输出必须是原始的二进制数据, 否则签名失败 : $signstr = base64_encode(hash_hmac('sha1', $srcstr, $secret_key, true).$srcstr); $srcwithfile = base64_encode(hash_hmac('sha1', $srcwithfile, $secret_key, true).$srcwithfile ); $signstronce = base64_encode(hash_hmac('sha1',$srcstronce,$secret_key, true).$srcstronce); echo $signstr."\n"; echo $srcwithfile."\n"; echo $signstronce."\n"; JAVA 签名示例 /* * Copyright 2017, Tencent Inc * All rights reserved. * * Created on 2017 年 9 月 12 日 */ package sign; import java.util.base64; import java.util.random; import javax.crypto.mac; import javax.crypto.spec.secretkeyspec; public class Sign { /** * 生成 Authorization 签名字段 * appid secretid secretkey bucketname expired 第 21 共 102 页

22 Exception */ public static String appsign(long appid, String secretid, String secretkey, String bucketname, long expired) throws Exception { long now = System.currentTimeMillis() / 1000; int rdm = Math.abs(new Random().nextInt()); String plaintext = String.format("a=%d&b=%s&k=%s&t=%d&e=%d&r=%d", appid, bucketname, secretid, now, now + expired, rdm); byte[] hmacdigest = HmacSha1(plainText, secretkey); byte[] signcontent = new byte[hmacdigest.length + plaintext.getbytes().length]; System.arraycopy(hmacDigest, 0, signcontent, 0, hmacdigest.length); System.arraycopy(plainText.getBytes(), 0, signcontent, hmacdigest.length, plaintext.getbytes().length); return Base64Encode(signContent); } /** * 生成 base64 编码 * binarydata */ public static String Base64Encode(byte[] binarydata) { String encodedstr = Base64.getEncoder().encodeToString(binaryData); return encodedstr; } /** * 生成 hmacsha1 签名 * binarydata key Exception */ public static byte[] HmacSha1(byte[] binarydata, String key) throws Exception { Mac mac = Mac.getInstance("HmacSHA1"); SecretKeySpec secretkey = new SecretKeySpec(key.getBytes(), "HmacSHA1"); mac.init(secretkey); byte[] HmacSha1Digest = mac.dofinal(binarydata); return HmacSha1Digest; } /** 第 22 共 102 页

23 * 生成 hmacsha1 签名 * plaintext key Exception */ public static byte[] HmacSha1(String plaintext, String key) throws Exception { return HmacSha1(plainText.getBytes(), key); } } Node JS 签名示例 var crypto = require('crypto'); var secretid = 'YOUR SECRET_ID', secretkey = 'YOUR SECRET_KEY', appid = 'APPID', pexpired = 86400, userid = 0; var now = parseint(date.now() / 1000), rdm = parseint(math.random() * Math.pow(2, 32)), plaintext = 'a=' + appid + '&k=' + secretid + '&e=' + (now+pexpired) + '&t=' + now + '&r=' + rdm + userid + '&f=', data = new Buffer(plainText,'utf8'), res = crypto.createhmac('sha1',secretkey).update(data).digest(), bin = Buffer.concat([res,data]); var sign = bin.tostring('base64'); C++ 签名示例 //g++ -g sign_sample.cpp -o sign -lcrypto #include <stdio.h> #include <stdlib.h> /* srand, rand */ 第 23 共 102 页

24 #include <time.h> /* time */ #include <openssl/hmac.h> #include <openssl/pem.h> #include <openssl/bio.h> #include <openssl/evp.h> #include <string> #include <vector> #include <sstream> #define HMAC_LENGTH 20 std::vector<unsigned char> hmac_sha1(std::string& data, std::string& key) { unsigned char* result; unsigned int len = HMAC_LENGTH; result = (unsigned char*)malloc(sizeof(char) * len); HMAC_CTX ctx; HMAC_CTX_init(&ctx); HMAC_Init_ex(&ctx, key.c_str(), key.length(), EVP_sha1(), NULL); HMAC_Update(&ctx, (unsigned char*)data.c_str(), data.length()); HMAC_Final(&ctx, result, &len); HMAC_CTX_cleanup(&ctx); std::vector<unsigned char> sha1; for (int i = 0; i < len; i++){ sha1.push_back(result[i]); } free(result); return sha1; } std::string base64_encode(const std::string& src){ BUF_MEM * bptr = NULL; BIO* b64 = BIO_new(BIO_f_base64()); BIO_set_flags(b64, BIO_FLAGS_BASE64_NO_NL); BIO* bmem = BIO_new(BIO_s_mem()); if(null == b64 NULL == bmem){ return ""; } bmem = BIO_push(b64, bmem); 第 24 共 102 页

25 int ret = BIO_write(bmem, src.data(), src.length()); if(ret <= 0){ return ""; } ret = BIO_flush(bmem); BIO_get_mem_ptr(bmem, &bptr); std::string res(bptr->data, bptr->length); BIO_free_all(bmem); return res; } int main() { std::string appid = " "; std::string secret_id = "YOUR SECRETID"; std::string secret_key = "YOUR SECRETKEY"; time_t now = time(null); long expired = (long)now ; long onceexpired = 0; long current = (long)now; int rdm = rand(); std::string userid = "0"; std::stringstream raw_stream; raw_stream << "a=" << appid << "&k=" << secret_id << "&e=" << expired << "&t=" << current << "&r=" << rdm; std::string raw = raw_stream.str(); std::vector<unsigned char> sha1 = hmac_sha1(raw, secret_key); std::stringstream data_stream; for (int i = 0; i!= sha1.size(); i++) data_stream << sha1[i]; data_stream << raw; std::string data = data_stream.str(); std::string sign = base64_encode(data); printf("%s\n", sign.c_str()); return 0; } 第 25 共 102 页

26 签名适用场景 签名的适用场景有如下限制 : 场景智能鉴黄图片标签 OCR 识别人脸识别人脸核身人脸融合 适用签名多次有效签名多次有效签名多次有效签名多次有效签名多次有效签名多次有效签名 第 26 共 102 页

27 人脸检测 最近更新时间 : :52:09 接口描述 接口请求域名 : 本接口 (detect) 用于检测给定图片中的所有人脸 ( Face ) 的位置和相应的面部属性, 位置包括 (x,y,w,h), 面部属性包括性别 ( gender ) 年龄( age ) 表情( expression ) 魅力( beauty ) 眼镜( glass ) 和姿态 (pitch,roll, yaw ) 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名 多次有效签名, 用于鉴权, 生成方式见鉴 权签名 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 第 27 共 102 页

28 输入参数 使用 application/json 格式, 参数选择 url ; 使用 multipart/form-data 格式, 参数选择 image 参数名 必选 类型 参数说明 appid 是 String 接入项目的唯一标识, 可在账号信息或云 API 密钥中查看 mode 否 Int 检测模式,0: 所有人脸,1: 最大的人脸 image 否 Binary 图片内容 url 否 String 图片的 url image 提供一个即可 ; 如果都提供, 只使用 url 输出参数 字段 类型 说明 data.session_id String 相应请求的 session 标识符, 可用于结果查询 data.image_width Int 请求图片的宽度 data.image_height Int 请求图片的高度 data.face Array(faceItem) 检测出的人脸信息列表 code Int 返回状态码 message String 返回错误消息 FaceItem 说明 : 字段 类型 说明 face_id String 人脸标识 x Int 人脸框左上角 x y Int 人脸框左上角 y width Float 人脸框宽度 height Float 人脸框高度 第 28 共 102 页

29 字段类型说明 gender Int 性别 [0(female)~100(male)] age Int 年龄 [0~100] expression Int 微笑 [0(normal)~50(smile)~100(laugh)] glass Bool 是否有眼镜 [true,false] pitch Int 上下偏移 [-30,30] yaw Int 左右偏移 [-30,30] roll Int 平面旋转 [-180,180] Beauty Int 魅力 [0~100] 注意 : 如果图片中包含超过 5 张人脸, 在返回的 FaceItem 中, 只返回 5 张人脸完整信息, 其他人脸只返回位置信息 (face_id,x,y,width,height), 属性信息不返回 示例 输入示例 使用 url 的请求包 POST /face/detect HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 123 Content-Type: application/json { "appid":"123456", "mode":1, "url":" } 使用 image 的请求包 第 29 共 102 页

30 POST /face/detect HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 460 Content-Type: multipart/form-data;boundary= acebdf acebdf Content-Disposition: form-data; name="appid"; acebdf Content-Disposition: form-data; name="mode"; acebdf Content-Disposition: form-data; name="image"; filename="test.jpg" Content-Type: image/jpeg xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx acebdf 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 313 Content-Type: application/json { "data":{ "session_id": "", "image_height": 200, "image_width": 200, "face": [{ "face_id": " ", "x": 44, "y": 33, "height": 64.0, "width": 64.0, "pitch": 5, "roll": 0, "yaw": 6, "age": 37, "gender": 99, 第 30 共 102 页

31 "glass": true, "expression": 6 "beauty": 80 }] }, "code":0, "message":"ok" } 错误码 错误码 含义 3 错误的请求, 其中 message:account abnormal,errorno is:2 为账号欠费停服 4 签名为空 5 签名串错误 6 签名中的 APPID / 存储桶与操作目标不匹配 9 签名过期 10 APPID 不存在 11 SecretId 不存在 12 APPID 和 SecretId 不匹配 13 重放攻击 14 签名校验失败 15 操作太频繁, 触发频控 16 存储桶不存在 21 无效参数 23 请求包体过大 107 鉴权服务不可用 108 鉴权服务不可用 213 内部错误 第 31 共 102 页

32 错误码 含义 人脸检测失败 图片解码失败 特征处理失败 提取轮廓错误 提取性别错误 提取表情错误 提取年龄错误 提取姿态错误 提取眼镜错误 特征存储错误 图片为空 参数为空 个体已存在 个体不存在 参数过长 人脸不存在 组不存在 组列表不存在 url 图片下载失败 人脸个数超过限制 个体个数超过限制 组个数超过限制 对个体添加了几乎相同的人脸 参数不合法 ( 特殊字符比如空格 斜线 tab 换行符) 第 32 共 102 页

33 错误码 含义 非法的图片格式 图片下载失败 更多其他 API 错误码请查看错误码说明 第 33 共 102 页

34 五官定位 最近更新时间 : :28:51 接口描述 接口请求域名 : 本接口 (shape) 用于对请求图片进行五官定位, 计算构成人脸轮廓的 88 个点, 包括眉毛 ( 左右各 8 点 ) 眼睛 ( 左右各 8 点 ) 鼻子 ( 13 点 ) 嘴巴 ( 22 点 ) 脸型轮廓 ( 21 点 ) 各部分的点的顺序如下图所示 : 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 第 34 共 102 页

35 输入参数 参数名 必选 类型 参数说明 appid 是 String 接入项目的唯一标识, 可在账号信息或云 API 密钥中查看 mode 否 Int 检测模式,0: 所有人脸,1: 最大的人脸 image 否 Binary 图片内容 url 否 String 图片的 url,image 和 url 只需提供一个 ; 如果都提供, 只使用 url 输出参数 字段 类型 说明 data.session_id String 相应请求的 session 标识符, 可用于结果查询 data.image_width Int 请求图片的宽度 data.image_height Int 请求图片的高度 data.face_shape.face_profile Array(Point) 描述脸型轮廓的 21 点 data.face_shape.left_eye Array(Point) 描述左测眼睛轮廓的 8 点 data.face_shape.right_eye Array(Point) 描述右测眼睛轮廓的 8 点 data.face_shape.left_eyebrow Array(Point) 描述左测眉毛轮廓的 8 点 data.face_shape.right_eyebrow Array(Point) 描述右测眉毛轮廓的 8 点 data.face_shape.mouth Array(Point) 描述嘴巴轮廓的 22 点 data.face_shape.nose Array(Point) 描述鼻子轮廓的 13 点 code Int 返回状态码 message String 返回错误消息 Point 说明 : 字段类型说明 第 35 共 102 页

36 字段类型说明 x Int 坐标 x, 图片左上角为 0 y Int 坐标 y, 图片左上角为 0 示例 输入示例 使用 url POST /face/shape HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 123 Content-Type: application/json { "appid":"123456", "mode":1, "url":" } 使用 image POST /face/shape HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 460 Content-Type: multipart/form-data;boundary= acebdf acebdf Content-Disposition: form-data; name="appid"; acebdf Content-Disposition: form-data; name="mode"; acebdf Content-Disposition: form-data; name="image"; filename="test.jpg" Content-Type: image/jpeg 第 36 共 102 页

37 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx acebdf 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 313 Content-Type: application/json { "data":{ "session_id": "", "image_height": 200, "image_width": 200, "face_shape": [{ "face_profile": [{"x":48,"y":55},{"x":49,"y":61},{"x":49,"y":66},{"x":50,"y":71},{"x":51,"y":76},{"x":54,"y":81},{"x": 56,"y":86},{"x":60,"y":90},{"x":65,"y":93},{"x":71,"y":95},{"x":77,"y":96},{"x":82,"y":95},{"x":87,"y":93},{"x":92, "y":90},{"x":94,"y":85},{"x":97,"y":81},{"x":99,"y":76},{"x":100,"y":71},{"x":101,"y":65},{"x":101,"y":60},{"x":101, "y":55}], "left_eye":[{"x":62,"y":55},{"x":64,"y":56},{"x":66,"y":57},{"x":68,"y":57},{"x":70,"y":56},{"x":69,"y":54},{"x":66, "y":54},{"x":64,"y":54}], "right_eye":[{"x":92,"y":55},{"x":90,"y":56},{"x":88,"y":56},{"x":86,"y":56},{"x":84,"y":56},{"x":85,"y":54},{"x":88, "y":53},{"x":90,"y":54}], "left_eyebrow":[{"x":56,"y":50},{"x":61,"y":50},{"x":65,"y":50},{"x":68,"y":50},{"x":73,"y":50},{"x":69,"y":47},{"x" :64,"y":46},{"x":60,"y":47}], "right_eyebrow":[{"x":97,"y":50},{"x":93,"y":50},{"x":89,"y":50},{"x":86,"y":50},{"x":82,"y":50},{"x":85,"y":47},{ "x":90,"y":46},{"x":95,"y":46}], "mouth":[{"x":67,"y":80},{"x":70,"y":83},{"x":74,"y":85},{"x":78,"y":85},{"x":81,"y":84},{"x":83,"y":82},{"x":86, "y":80},{"x":84,"y":78},{"x":81,"y":77},{"x":78,"y":78},{"x":74,"y":78},{"x":71,"y":79},{"x":71,"y":81},{"x":74,"y":8 1},{"x":78,"y":81},{"x":80,"y":80},{"x":83,"y":80},{"x":83,"y":79},{"x":80,"y":79},{"x":78,"y":80},{"x":74,"y":80},{ "x":71,"y":80}], "nose":[{"x":79,"y":68},{"x":77,"y":56},{"x":75,"y":60},{"x":74,"y":64},{"x":72,"y":67},{"x":70,"y":70},{"x":74,"y":7 2},{"x":78,"y":72},{"x":81,"y":72},{"x":85,"y":70},{"x":83,"y":66},{"x":81,"y":63},{"x":81,"y":59}] }] }, "code":0, "message":"ok" } 错误码 第 37 共 102 页

38 API 错误码请查看错误码说明 第 38 共 102 页

39 人脸比对 最近更新时间 : :27:20 接口描述 接口请求域名 : 本接口 (compare) 用于计算两个 Face 的相似性以及五官相似度 说明 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 请求包 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 根据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名 多次有效签名, 用于鉴权, 生成方式见鉴 权签名方法 注意 : 选择 multipart/form-data 时, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type 如果直接调用 setheader 等方法设置, 可能会导致 boundary 缺失引起请求失败 输入参数 第 39 共 102 页

40 使用 application/json 格式, 参数选择 url ; 使用 multipart/form-data 格式, 参数选择 image 参数名必选类型参数说明 appid 是 String 接入项目的唯一标识, 可在账号信息或云 API 密钥中查看 imagea 否 Binary A 图片内容 imageb 否 Binary B 图片内容 urla 否 String A 图片的 url,image 和 url 只需提供一个 ; 如果都提供, 只使用 url urlb 否 String B 图片的 url,image 和 url 只需提供一个 ; 如果都提供, 只使用 url 输出参数 字段类型说明 data.session_id String 相应请求的 session 标识符 data.similarity Float 两个 face 的相似度 data.fail_flag Int 标志失败图片,1 为第一张,2 为第二张 ( 失败时返回 ) code Int 返回码 message String 返回错误消息 示例 输入示例 使用 url POST /face/compare HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 123 Content-Type: application/json { "appid":"123456", "urla":" 第 40 共 102 页

41 "urlb":" } 使用 image POST /face/compare HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 460 Content-Type: multipart/form-data;boundary= acebdf acebdf Content-Disposition: form-data; name="appid"; acebdf Content-Disposition: form-data; name="imagea"; filename="testa.jpg" Content-Type: image/jpeg xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx acebdf Content-Disposition: form-data; name="imageb"; filename="testb.jpg" Content-Type: image/jpeg xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx acebdf 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 109 Content-Type: application/json { "data":{ "similarity":100.0, "session_id":"" }, "code":0, "message":"ok" } 第 41 共 102 页

42 错误码 错误码 含义 3 错误的请求 ; 其中 message:account abnormal,errorno is:2 为账号欠费停服 4 签名为空 5 签名串错误 6 签名中的 APPID / 存储桶与操作目标不匹配 9 签名过期 10 APPID 不存在 11 SecretId 不存在 12 APPID 和 SecretId 不匹配 13 重放攻击 14 签名校验失败 15 操作太频繁, 触发频控 16 存储桶不存在 21 无效参数 23 请求包体过大 107 鉴权服务不可用 108 鉴权服务不可用 213 内部错误 人脸检测失败 图片解码失败 特征处理失败 提取轮廓错误 提取性别错误 第 42 共 102 页

43 错误码 含义 提取表情错误 提取年龄错误 提取姿态错误 提取眼镜错误 特征存储错误 图片为空 参数为空 个体已存在 个体不存在 参数过长 人脸不存在 组不存在 组列表不存在 url 图片下载失败 人脸个数超过限制 个体个数超过限制 组个数超过限制 对个体添加了几乎相同的人脸 参数不合法 ( 特殊字符比如空格 斜线 tab 换行符) 非法的图片格式 图片下载失败 更多其他 API 错误码请查看错误码说明 第 43 共 102 页

44 个体信息管理 最近更新时间 : :07:01 个体创建 接口描述接口请求域名 : 本接口 (newperson) 用于创建一个 person, 并将 person 放置到 group_ids 指定的组当中, 不存在的 group_id 会自动创建 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 输入参数 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url ; 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名 多次有效签名, 用于鉴权, 生成方式见鉴 权签名方法 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 第 44 共 102 页

45 请求参数 使用 application/json 格式, 参数选择 url ; 使用 multipart/form-data 格式, 参数选择 image 参数名必选类型参数说明 appid 是 String 接入项目的唯一标识, 可在账号信息或云 API 密钥中查看 group_ids 是 Array(String) 加入到组的列表 person_id 是 String 指定的个体 ID image 否 binary 图片内容 url 否 String 图片的 url image 提供一个即可 ; 如果都提供, 只使用 url person_name 否 String 名字 tag 否 String 备注信息 输出参数 字段类型说明 data.session_id String 相应请求的 session 标识符 data.suc_group Int 成功被加入的 group 数量 data.suc_face Int 成功加入的 face 数量 data.person_id String 相应 person 的 ID data.face_id String 创建所用图片生成的 face_id data.group_ids Array(string) 加入成功的组 ID code Int 返回码 message String 返回错误消息 示例 输入示例 使用 url 的输入示例 : POST /face/newperson HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== 第 45 共 102 页

46 Host: recognition.image.myqcloud.com Content-Length: 187 Content-Type: application/json { "appid":"123456", "group_ids":[ "tencent", "qq" ], "person_id":"person0", "url":" } 使用 image 的输入示例 : POST /face/newperson HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 735 Content-Type: multipart/form-data;boundary= acebdf acebdf Content-Disposition: form-data; name="appid"; acebdf Content-Disposition: form-data; name="group_ids[0]"; tencent acebdf Content-Disposition: form-data; name="group_ids[1]"; qq acebdf Content-Disposition: form-data; name="person_id"; person acebdf Content-Disposition: form-data; name="image"; filename="test.jpg" Content-Type: image/jpeg xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx acebdf 返回示例 第 46 共 102 页

47 HTTP/ OK Connection: keep-alive Content-Length: 204 Content-Type: application/json { "data":{ "person_id":"person0", "suc_group":2, "suc_face":1, "session_id":"", "face_id":" ", "group_ids":["tencent", "qq"] }, "code":0, "message":"ok" } 删除个体 接口描述 接口请求示例 : 本接口 (delperson) 用于删除一个 Person 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 输入参数 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 第 47 共 102 页

48 参数名必选值描述 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url ; 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名 多次有效签名, 用于鉴权, 生成方式见鉴 权签名方法 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 请求参数 使用 application/json 格式 参数名必选类型参数说明 appid 是 String 项目 ID person_id 是 String 待删除个体 ID 输出参数 字段类型说明 data.session_id String 相应请求的 session 标识符 data.person_id String 成功删除的 person_id data.deleted Int 成功删除的 person 数量 code Int 返回状态码 message String 返回错误消息 示例 输入示例 第 48 共 102 页

49 POST /face/delperson HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 66 Content-Type: application/json { "appid":"123456", "person_id":"person0" } 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 114 Content-Type: application/json { "data":{ "deleted": 1, "person_id": "person0", "session_id":"" }, "code":0, "message":"ok" } 增加人脸 接口描述 接口请求域名 : 本接口 (addface) 用于将一组 face 加入到一个 person 中 一个 person 最多允许包含 20 个 face 注意 : 加入相似度为 [99%-100%] 的人脸会返回错误 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 第 49 共 102 页

50 输入参数 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url ; 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名鉴权签名, 详见签名与鉴权 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 请求参数 使用 application/json 格式, 参数选择 url ; 使用 multipart/form-data 格式, 参数选择 image 参数名必选类型参数说明 appid 是 String 接入项目的唯一标识, 可在账号信息或云 API 密钥中查看 person_id 是 String 待增加人脸的个体 ID images 否 Array(Binary) 图片内容 urls 否 String 图片的 urls image 提供一个即可 ; 如果都提供, 只使用 urls tag 否 String 备注信息 输出参数 字段类型说明 data.session_id String 相应请求的 session 标识符 第 50 共 102 页

51 字段类型说明 data.added Int 成功加入的 face 数量 data.face_ids Array(String) 增加的人脸 ID 列表 data.ret_codes array(int) 每张图片增加人脸的返回码 code Int 返回状态码 message String 返回错误消息 示例 输入示例 使用 url 的输入示例 : POST /face/addface HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 191 Content-Type: application/json { "appid":"123456", "person_id":"person0", "urls":[ " " ] } 使用 image 的输入示例 : POST /face/addface HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 641 Content-Type: multipart/form-data;boundary= acebdf acebdf Content-Disposition: form-data; name="appid"; 第 51 共 102 页

52 acebdf Content-Disposition: form-data; name="person_id"; person acebdf Content-Disposition: form-data; name="images[0]"; filename="face1.jpg" Content-Type: image/jpeg yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy acebdf Content-Disposition: form-data; name="images[1]"; filename="face2.jpg" Content-Type: image/jpeg xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx acebdf 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 168 Content-Type: application/json { "data":{ "added":2, "session_id":"", "face_ids":[" "," "], "ret_codes":[0, 0] }, "code":0, "message":"ok" } 删除人脸 接口描述 接口请求域名 : 本接口 (delface) 用于删除一个 person 下的 face, 包括特征 属性和 face id 注意 : 第 52 共 102 页

53 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 输入参数 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url ; 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名鉴权签名, 详见签名与鉴权 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 请求参数 使用 application/json 格式 参数名必选类型参数说明 appid 是 String 项目 ID person_id 是 String 待删除人脸的 person id face_ids 是 Array(String) 删除人脸 ID 的列表 输出参数 字段类型说明 data.session_id String 相应请求的 session 标识符 第 53 共 102 页

54 字段类型说明 data.deleted Int 成功删除的 face 数量 data.face_ids Array(String) 成功删除的 face_id 列表 code Int 返回状态码 message String 返回错误消息 示例 输入示例 POST /face/delface HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 125 Content-Type: application/json { "appid":"123456", "person_id":"person0", "face_ids":[ "199d1efd19ce4ee67a7ec7655f859b1a" ] } 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 150 Content-Type: application/json { "data":{ "deleted": 1, "face_ids":[ "199d1efd19ce4ee67a7ec7655f859b1a" ], "session_id":"" }, "code":0, 第 54 共 102 页

55 "message":"ok" } 设置信息 接口描述 接口请求域名 : 本接口 (setinfo) 用于设置 person 的 name 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 输入参数 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url ; 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名鉴权签名, 详见签名与鉴权 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 请求参数 使用 application/json 格式 第 55 共 102 页

56 参数名必选类型参数说明 appid 是 String 项目 ID person_id 是 String 相应 person 的 ID person_name 否 String 新的 name tag 否 String 备注信息 输出参数 字段类型说明 data.session_id String 相应请求的 session 标识符 data.person_id String 相应 person 的 ID code Int 返回状态码 message String 返回错误消息 示例 输入示例 POST /face/setinfo HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 97 Content-Type: application/json { "appid":"123456", "person_id":"person0", "person_name":"nicolascage" } 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 96 Content-Type: application/json 第 56 共 102 页

57 { "data":{ "person_id": "person0", "session_id":"" }, "code":0, "message":"ok" } 获取信息 接口描述 接口请求域名 : 本接口 (getinfo) 用于获取一个 person 的信息, 包括 name, id, tag, 相关的 face, 以及 groups 等信息 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 输入参数 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url ; 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名鉴权签名, 详见签名与鉴权 注意 : 第 57 共 102 页

58 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 请求参数 使用 application/json 格式 参数名必选类型参数说明 appid 是 String 项目 ID person_id 是 String 待查询个体的 ID 输出参数 字段类型说明 data.person_name String 相应 person 的 name data.person_id String 相应 person 的 ID data.face_ids Array(String) 包含的人脸列表 data.group_ids Array(String) 包含此个体的组 ID data.session_id String 相应请求的 session 标识符 data.tag String 为此个体设置的备注信息 code Int 返回状态码 message String 返回错误消息 示例 输入示例 POST /face/getinfo HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 66 Content-Type: application/json { "appid":"123456", 第 58 共 102 页

59 "person_id":"person0" } 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 293 Content-Type: application/json { "data":{ "person_id": "person0", "person_name": "NicolasCage", "face_ids": [ "199d1efd19ce4ee67a7ec7655f859b1a", "19321efd19ce4ee67a f85934a" ], "group_ids":[ "tencent" ], "tag":"", "session_id":"" }, "code":0, "message":"ok" } 获取组列表 接口描述 接口请求域名 : 本接口 (getgroupids) 用于获取一个 APPID 下所有 group 列表 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 输入参数 第 59 共 102 页

60 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url ; 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名鉴权签名, 详见签名与鉴权 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 请求参数 使用 application/json 格式 参数名必选类型参数说明 appid 是 String 项目 ID 输出参数 字段类型说明 data.group_ids Array(String) 相应 appid 的 group_id 列表 code Int 返回状态码 message String 返回错误消息 示例 输入示例 第 60 共 102 页

61 POST /face/getgroupids HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 41 Content-Type: application/json { "appid":"123456" } 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 136 Content-Type: application/json { "data":{ "group_ids": [ "tencent", "tencent-beijing", "tencent-shanghai" ] }, "code":0, "message":"ok" } 获取人列表 接口描述 接口请求域名 : 本接口 (getpersonids) 用于获取一个组 group 中所有 person 列表 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 第 61 共 102 页

62 输入参数 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url ; 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名鉴权签名, 详见签名与鉴权 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 请求参数 使用 application/json 格式 参数名必选类型参数说明 appid 是 String 项目 ID group_id 是 String 组 ID 输出参数 字段类型说明 data.person_ids Array(String) 相应 person 的 ID 列表 code Int 返回状态码 message String 返回错误消息 示例 第 62 共 102 页

63 输入示例 POST /face/getpersonids HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 65 Content-Type: application/json { "appid":"123456", "group_id":"tencent" } 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 120 Content-Type: application/json { "data":{ "person_ids": [ "person0", "person1", "person2" ] }, "code":0, "message":"ok" } 获取人脸列表 接口描述 接口请求域名 : 本接口 (getfaceids) 用于获取一个组 person 中所有 face 列表 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 第 63 共 102 页

64 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 输入参数 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url ; 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名鉴权签名, 详见签名与鉴权 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 请求参数 使用 application/json 格式 参数名必选类型参数说明 appid 是 String 项目 ID person_id 是 String 个体 ID 输出参数 字段类型说明 data.face_ids Array(String) 相应 face 的 ID 列表 code Int 返回状态码 message String 返回错误消息 第 64 共 102 页

65 示例 输入示例 POST /face/getfaceids HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 66 Content-Type: application/json { "appid":"123456", "person_id":"person1" } 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 154 Content-Type: application/json { "data":{ "face_ids": [ " ", " ", " " ] }, "code":0, "message":"ok" } 获取人脸信息 接口描述 接口请求域名 : 本接口 (getfaceinfo) 用于获取一个 face 的相关特征信息 注意 : 第 65 共 102 页

66 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 输入参数 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url ; 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名鉴权签名, 详见签名与鉴权 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 请求参数 使用 application/json 格式 参数名必选类型参数说明 appid 是 String 项目 ID face_id 是 String 人脸 ID 输出参数 字段类型说明 data.face_info faceitem 人脸信息 code Int 返回状态码 第 66 共 102 页

67 字段类型说明 message String 返回错误消息 faceitem 说明 字段类型说明 face_id String 人脸标识 x Int 人脸框左上角 x y Int 人脸框左上角 y width Float 人脸框宽度 height Float 人脸框高度 gender Int 性别 [0(female)~100(male)] age Int 年龄 [0~100] expression Int 微笑 [0(normal)50(smile)100(laugh)] glass Bool 是否有眼镜 [true,false] pitch Int 上下偏移 [-30,30] yaw Int 左右偏移 [-30,30] roll Int 平面旋转 [-180,180] 示例 输入示例 POST /face/getfaceinfo HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 76 Content-Type: application/json { "appid":"123456", "face_id":" " } 第 67 共 102 页

68 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 313 Content-Type: application/json { "data":{ "face_info": { "face_id": " ", "x": 44, "y": 33, "height": 64.0, "width": 64.0, "pitch": 5, "roll": 0, "yaw": 6, "age": 37, "gender": 99, "glass": true, "expression": 6 } }, "code":0, "message":"ok" } Person 新增组信息 接口描述 接口请求域名 : 本接口 (addgroupids) 用于为一个 person 新增 group_id 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 输入参数 第 68 共 102 页

69 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url ; 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名 多次有效签名, 用于鉴权, 生成方式见鉴 权签名方法 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 请求参数 使用 application/json 格式 参数名必选类型参数说明 appid 是 String 项目 ID person_id 是 String 人脸 ID group_ids 是 Array group ID session_id 否 String 会话 ID 输出参数 字段类型说明 data groupsadditem 结果信息 code Int 返回状态码 第 69 共 102 页

70 字段类型说明 message String 返回错误消息 groupsadditem 说明 字段类型说明 person_id String person ID added Int 成功新增组数 group_ids Array 当前人所在组信息 session_id String 会话 ID Person 删除组信息 接口描述 接口请求域名 : 本接口 (delgroupids) 用于为一个 person 删除 group_id 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 输入参数 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 第 70 共 102 页

71 参数名必选值描述 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url ; 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名鉴权签名, 详见签名与鉴权 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 请求参数 使用 application/json 格式 参数名必选类型参数说明 appid 是 String 项目 ID person_id 是 String 人脸 ID group_ids 是 Array group ID session_id 否 String 会话 ID 输出参数 字段类型说明 data groupsadditem 结果信息 code Int 返回状态码 message String 返回错误消息 Groupsadditem 说明 字段类型说明 person_id String personid 第 71 共 102 页

72 字段 类型 说明 deleted Int 成功删除组数 group_ids Array 当前人所在组信息 session_id String 会话 ID 错误码 错误码 含义 3 错误的请求 ; 其中 message:account abnormal,errorno is:2 为账号欠费停服 4 签名为空 5 签名串错误 6 签名中的 APPID/ 存储桶与操作目标不匹配 9 签名过期 10 APPID 不存在 11 SecretId 不存在 12 APPID 和 SecretId 不匹配 13 重放攻击 14 签名校验失败 15 操作太频繁, 触发频控 16 存储桶不存在 21 无效参数 23 请求包体过大 107 鉴权服务不可用 108 鉴权服务不可用 213 内部错误 第 72 共 102 页

73 错误码 含义 人脸检测失败 图片解码失败 特征处理失败 提取轮廓错误 提取性别错误 提取表情错误 提取年龄错误 提取姿态错误 提取眼镜错误 特征存储错误 图片为空 参数为空 个体已存在 个体不存在 参数过长 人脸不存在 组不存在 组列表不存在 url 图片下载失败 人脸个数超过限制 个体个数超过限制 组个数超过限制 对个体添加了相似度为 99% 及以上的人脸 参数不合法 ( 特殊字符比如空格 斜线 tab 换行符) 第 73 共 102 页

74 错误码 含义 非法的图片格式 图片下载失败 更多其他 API 错误码请查看错误码说明 第 74 共 102 页

75 人脸验证 最近更新时间 : :24:53 接口描述 接口请求域名 : 本接口 (verify) 用于给定一个图片和一个 Person 时, 检查是否是同一个人 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 基本概念 概念 解释 appid 接入项目的唯一标识, 可在账号信息或云 API 密钥中查看 group_id person_id face_id 个体 ( person ) 以组 ( group ) 的形式存储, 一个组可以包含多个个体, 一个个体也可以存在于多个组 group_id 即用来标识 group 组( group ) 没有专门的创建接口, 创建个体 ( person ) 时, 指定 group_id 则会自动创建 人脸以个体 ( person ) 的形式存储, 一个个体下可以存储多张人脸 person_id 即用来标识 person 标识每张人脸的 ID 说明 : 如果开发者使用的是 V1 版本, 则 APPID 为其当时生成的 APPID group 信息管理接口如下 : 接口 创建个 体 描述 创建一个 person, 并将 person 放置到 group_ids 指定的组当中, 不存在的 group_id 会自动创 建 第 75 共 102 页

76 接口 描述 删除个体增加人脸 删除一个 person 将一组 face 加入到一个 person 中 一个 face 只能被加入到一个 person 中 一个 person 最多 允许包含 20 个 face ; 加入几乎相同的人脸会返回错误 删除人 脸 删除一个 person 下的 face, 包括特征, 属性和 face_id 设置信 息 设置 person 的 name 获取信 息 获取一个 person 的信息, 包括 name ID tag 相关的 face 以及 groups 等信息 获取组 列表 获取一个 APPID 下所有 group 列表 获取人 列表 获取一个 group 中所有 person 列表 获取人 脸列表 获取一个组 person 中所有 face 列表 获取人 脸信息 获取一个 face 的相关特征信息 说明 : 一个 APPID 下建立的 group_id 数量限制为 5000 个 一个 group_id 下建立的 person_id 数量限制为 个 一个 person_id 下建立的人脸数量限制为 20 个 每个请求的包体大小限制为 1.5MB, 不支持.gif 类型的动图 输入参数 请求头 header 使用 application/json 格式, 参数选择 url; 使用 multipart/form-data 格式, 参数选择 image 参数名必选类型参数说明 appid 是 String 接入项目的唯一标识, 可在账号信息或云 API 密钥中查看 第 76 共 102 页

77 参数名必选类型参数说明 person_id 是 String 待验证的 person image 否 Binary 图片内容 url 否 String 图片的 url image 和 url 只提供一个就可以了, 如果都提供, 只使用 url 输出参数 字段类型说明 data.session_id String 相应请求的 session 标识符, 可用于结果查询 data.confidence Float 两个人的相似度 data.ismatch Bool 两个输入是否为同一人的判断 code Int 返回状态码 message String 返回错误消息 示例 输入示例 使用 url POST /face/verify HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 123 Content-Type: application/json { "appid":"123456", "person_id":"person1", "url":" } 使用 image 第 77 共 102 页

78 POST /face/verify HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 460 Content-Type: multipart/form-data;boundary= acebdf acebdf Content-Disposition: form-data; name="appid"; acebdf Content-Disposition: form-data; name="person_id"; Person acebdf Content-Disposition: form-data; name="image"; filename="test.jpg" Content-Type: image/jpeg xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx acebdf 输出示例 HTTP/ OK Connection: keep-alive Content-Length: 409 Content-Type: application/json { "data":{ "session_id":"session_id", "confidence":90.0, "ismatch":true }, "code":0, "message":"ok" } 错误码 错误码 含义 第 78 共 102 页

79 错误码 含义 3 错误的请求 ; 其中 message:account abnormal,errorno is:2 为账号欠费停服 4 签名为空 5 签名串错误 6 签名中的 APPID / 存储桶与操作目标不匹配 9 签名过期 10 APPID 不存在 11 SecretId 不存在 12 APPID 和 SecretId 不匹配 13 重放攻击 14 签名校验失败 15 操作太频繁, 触发频控 16 存储桶不存在 21 无效参数 23 请求包体过大 107 鉴权服务不可用 108 鉴权服务不可用 213 内部错误 人脸检测失败 图片解码失败 特征处理失败 提取轮廓错误 提取性别错误 提取表情错误 提取年龄错误 第 79 共 102 页

80 错误码 含义 提取姿态错误 提取眼镜错误 特征存储错误 图片为空 参数为空 个体已存在 个体不存在 参数过长 人脸不存在 组不存在 组列表不存在 url 图片下载失败 人脸个数超过限制 个体个数超过限制 组个数超过限制 对个体添加了几乎相同的人脸 参数不合法 ( 特殊字符比如空格 斜线 tab 换行符) 非法的图片格式 图片下载失败 更多其他 API 错误码请查看错误码说明 第 80 共 102 页

81 人脸检索 最近更新时间 : :40:14 接口描述 接口请求域名 : 本接口 (identify) 用于对一张待识别的人脸图片, 在一个或多个 group 中识别出最相似的 Top5 person 作为其身 份返回, 返回的 Top5 中按照相似度从大到小排列 注意 : 本接口支持 HTTPS 协议, 如果您现在使用的是 HTTP 协议, 为了保障您的数据安全, 请切换至 HTTPS 如果开发者使用的是原域名 (service.image.myqcloud.com) 且已产生调用, 则无需更换域名 基本概念 概念 appid 解释 接入项目的唯一标识, 可在账号信息或云 API 密钥中查看 group_id person_id 个体 ( person ) 以组 ( group ) 的形式存储, 一个组可以包含多个个体, 一个个体也可以存在于多个组 group_id 即用来标识 group 组( group ) 没有专门的创建接口, 创建个体 ( person ) 时, 指定 group_id 则会自动创建 人脸以个体 ( person ) 的形式存储, 一个个体下可以存储多张人脸 person_id 即用来标识 person face_id 标识每张人脸的 ID 说明 : 如果开发者使用的是 V1 版本, 则 APPID 为其当时生成的 APPID group 信息管理接口如下 : 接口 创建个 体 描述 创建一个 person, 并将 person 放置到 group_ids 指定的组当中, 不存在的 group_id 会自动创 建 第 81 共 102 页

82 接口 描述 删除个体增加人脸 删除一个 person 将一组 face 加入到一个 person 中 注意, 一个 face 只能被加入到一个 person 中 一个 person 最多允许包含 20 个 face ; 加入几乎相同的人脸会返回错误 删除人 脸 删除一个 person 下的 face, 包括特征, 属性和 face_id 设置信 息 设置 person 的 name 获取信 息 获取一个 person 的信息, 包括 name ID tag 相关的 face 以及 groups 等信息 获取组 列表 获取一个 APPID 下所有 group 列表 获取人 列表 获取一个组 group 中所有 person 列表 获取人 脸列表 获取一个组 person 中所有 face 列表 获取人 脸信息 获取一个 face 的相关特征信息 说明 : 一个 APPID 下建立的 group_id 数量限制为 5000 个 一个 group_id 下建立的 person_id 数量限制为 个 一个 person_id 下建立的人脸数量限制为 20 个 每个请求的包体大小限制为 1.5MB, 不支持.gif 类型的动图 请求头 header 参数名必选值描述 host 是 recognition.image.myqcloud.com 腾讯云人脸识别服务器域名 第 82 共 102 页

83 参数名必选值描述 contentlength 否 包体总长度 整个请求包体内容的总长度, 单位 : 字节 (Byte) 据不同接口选择 : content-type 是 application/json 或 multipart/form-data 1. 使用 application/json 格式, 参数为 url, 其值为图片的 url 2. 使用 multipart/form-data 格式, 参数 为 image, 其值为图片的二进制内容 authorization 是鉴权签名 多次有效签名, 用于鉴权, 生成方式见鉴 权签名方法 注意 : 选择 multipart/form-data, 请使用 HTTP 框架 / 库推荐的方式设置请求的 content-type, 不推荐直接调用 setheader 等方法设置, 否则可能导致 boundary 缺失引起请求失败 输入参数 使用 application/json 格式时, 参数可选择 url 和 image, 此时 image 须为经 base64 编码后的 String, 参数类型为 String 使用 multipart/form-data 格式时, 参数可选择 url 和 image, 此时 image 须为 Binary 格式, 参数类型为 Binary 参数名必选类型参数说明 appid 是 String 接入项目的唯一标识, 可在账号信息或云 API 密钥中查看 group_id 否 String 候选人组 ID, 与 group_ids 二选一即可 group_ids 否 Array(String) 候选人组 ID 列表, 与 group_id 二选一即可 image 否 Binary 或 String 图片二进制内容或经 base64 转码后的字符串 url 否 String image 和 url 只需提供一个 ; 如果都提供, 只使用 url 输出参数 第 83 共 102 页

84 字段类型说明 data.session_id String 相应请求的 session 标识符, 可用于结果查询 data.candidates Array(IdentifyItem) 识别出的 Top5 候选人 code Int 返回状态码 message String 返回错误消息 IdentifyItem 说明 : 字段类型说明 person_id String 候选者 person_id face_id String 候选者 face_id confidence Float 候选者的置信度 tag String 人脸备注信息 示例 输入示例 使用 url POST /face/identify HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com Content-Length: 123 Content-Type: application/json { "appid":"123456", "group_id":"tencent", "url":" } POST /face/identify HTTP/1.1 Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi== Host: recognition.image.myqcloud.com 第 84 共 102 页