相同图片搜索
更新时间：2021-04-14
使用说明
在自建库中搜索相同图片，仅返回完全相同或局部相同的图片结果。
- 典型应用场景：图片去重、图片精确查找，如图片类站点对海量库存图片进行查重过滤
- 适用的图片类型：各种网络图片、实拍图均可；注意检索图和入库的原图要保持场景一致性，比如入库的原图为标准的广告图（无背景干扰），则检索图要尽量避免背景、其他干扰特征，否则模型计算图片的相似度时会有噪声，造成检索结果不准确。
举个例子：小张入库了5万张海报设计图，都是标准的电子版海报图片，无任何背景干扰；在线下活动时，要根据手机拍摄的海报图片判断是不是跟图库里的设计图重复了，手机实拍时要避免拍到海报图片之外的物体（如墙上的装饰、参加活动的人等各种背景元素），同时要拍到海报的全部或者大部分主体内容，不能只拍到一个海报的小角落就去检索，以免影响检索效果。
相同图片搜索包含入库、检索、删除、更新4个子接口；在正式使用之前请在控制台创建应用后，在应用详情页申请建库，建库成功后方可正常使用入库、检索、删除、更新接口。
申请建库时，图库的图片数量上限为50万，避免浪费资源；如果容量不够用，可在控制台-应用详情页 申请扩容，工作人员会在1-3个工作日内审批，每次扩容的申请上限也是50万，可以反复申请扩容，原则上图库总量无上限，百万级、千万级、甚至亿级的图片量都可以做到实时检索，秒级返回检索结果。
相同图片搜索—入库
该接口实现单张图片入库，入库时需要同步提交图片及可关联至本地图库的摘要信息（具体变量为brief，具体可传入图片在本地标记id、图片url、图片名称等）；同时可提交分类维度信息（具体变量为tags，最多可传入2个tag），方便对图库中的图片进行管理、分类检索。 注：重复添加完全相同的图片会返回错误。
Json::Value result;
std::string image;
aip::get_file_content("/assets/sample.jpg", &image);
// 调用相同图检索—入库, 图片参数为本地图片
result = client.same_hq_add(image, aip::null);
// 如果有可选参数
std::map<std::string, std::string> options;
options["brief"] = "{\"name\":\"周杰伦\", \"id\":\"666\"}";
options["tags"] = "100,11";
// 带参数调用相同图检索—入库, 图片参数为本地图片
result = client.same_hq_add(image, options);
Json::Value result;
std::string url = "http//www.x.com/sample.jpg";
// 调用相同图检索—入库, 图片参数为远程url图片
result = client.same_hq_add_url(url, aip::null);
// 如果有可选参数
std::map<std::string, std::string> options;
options["brief"] = "{\"name\":\"周杰伦\", \"id\":\"666\"}";
options["tags"] = "100,11";
// 带参数调用相同图检索—入库, 图片参数为远程url图片
result = client.same_hq_add_url(url, options);相同图片搜索—入库 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
| image | 否 | std::string | 图片数据的二进制字符串，可以使用aip::get_file_content函数获取，和url二选一，image优先级更高 |
| url | 否 | std::string | 图片完整URL，URL长度不超过1024字节。 URL对应的图片base64编码后大小不超过4M，最短边至少50px，最长边最大4096px；支持jpg/png/bmp格式，当image字段存在时url字段失效 。 由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传 |
| brief | 是 | std::string | 检索时原样带回,最长256B。样例：{"name":"周杰伦", "id":"666"} 。请注意，检索接口不返回原图，仅返回入库时填写的brief信息，所以调用入库接口时，brief信息请尽量填写可关联至本地图库的图片id或者图片url、图片名称等信息 |
| tags | 否 | std::string | 1 - 65535范围内的整数，tag间以逗号分隔，最多2个tag，tag间无层级关系。样例："100,11" ；检索时可圈定分类维度进行检索 |
相同图片搜索—入库 返回数据参数详情
| 字段 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
| log_id | 是 | uint64 | 唯一的log id，无实际意义，用于问题定位 |
| cont_sign | 是 | string | 入库图片的签名信息，请务必保存至本地，以便后续用作批量删除、查询某张图是否已经入过库等用途 |
相同图片搜索—入库 返回示例
{
"log_id": 2263663554,
"cont_sign": "4261577168,501945506"
}入库之后的图片，可在控制台的图库管理后台进行可视化管理，支持预览大图、更新摘要、更新分类信息、删除图片，入口在控制台-应用详情页 管理图库，注：大批量更新摘要或分类、删除图片请调用API。
同时，图库管理后台支持在线测试检索效果，点击右上角搜索框边上的“相机”标识，可以上传图片，测试检索效果。
相同图片搜索—检索
完成入库后，可使用该接口实现相同图检索。支持传入指定分类维度（具体变量tags）进行检索，返回结果支持翻页（具体变量pn、rn）。
注意：检索接口不返回原图，仅返回入库时填写的brief信息，请调用入库接口时尽量填写可关联至本地图库的图片id或者图片url等信息。
Json::Value result;
std::string image;
aip::get_file_content("/assets/sample.jpg", &image);
// 调用相同图检索—检索, 图片参数为本地图片
result = client.same_hq_search(image, aip::null);
// 如果有可选参数
std::map<std::string, std::string> options;
options["tags"] = "100,11";
options["tag_logic"] = "0";
options["pn"] = "100";
options["rn"] = "250";
// 带参数调用相同图检索—检索, 图片参数为本地图片
result = client.same_hq_search(image, options);
Json::Value result;
std::string url = "http//www.x.com/sample.jpg";
// 调用相同图检索—检索, 图片参数为远程url图片
result = client.same_hq_search_url(url, aip::null);
// 如果有可选参数
std::map<std::string, std::string> options;
options["tags"] = "100,11";
options["tag_logic"] = "0";
options["pn"] = "100";
options["rn"] = "250";
// 带参数调用相同图检索—检索, 图片参数为远程url图片
result = client.same_hq_search_url(url, options);相同图片搜索—检索 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
| image | 是 | std::string | 图片数据的二进制字符串，可以使用aip::get_file_content函数获取，和url二选一，image优先级更高 |
| url | 是 | std::string | 图片完整URL，URL长度不超过1024字节。 URL对应的图片base64编码后大小不超过4M，最短边至少50px，最长边最大4096px；支持jpg/png/bmp格式，当image字段存在时url字段失效 。 由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传 |
| tags | 否 | std::string | 1 - 65535范围内的整数，tag间以逗号分隔，最多2个tag。样例："100,11" ；检索时可圈定分类维度进行检索 |
| tag_logic | 否 | std::string | 检索时tag之间的逻辑， 0：逻辑and，1：逻辑or |
| pn | 否 | std::string | 分页功能，起始位置，例：0。未指定分页时，默认返回前300个结果；接口返回数量最大限制1000条，例如：起始位置为900，截取条数500条，接口也只返回第900 - 1000条的结果，共计100条 |
| rn | 否 | std::string | 分页功能，截取条数，例：250 |
相同图片搜索—检索 返回数据参数详情
| 字段 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
| log_id | 是 | uint64 | 唯一的log id，用于问题定位 |
| result_num | 是 | uint32 | 检索结果数 |
| result | 是 | object[] | 结果数组 |
| +cont_sign | 是 | string | 图片签名，可以用来删除图片或定位问题 |
| +score | 是 | float | 图片相关性，0-1 ，越接近1代表相关性越高 |
| +brief | 是 | string | 调用入库接口添加的brief信息，为保证该结果有效性，请入库时填写有效可关联至本地图片库的有效id信息 |
| has_more | 是 | bool | 是否还有下一页，返回值：true、false；如果不分页，不用关注该字段 |
相同图片搜索—检索 返回示例
{
"result_num": 1,
"result": [
{
"score": 0.97976700290421,
"brief": "./data/jay1.jpg",
"cont_sign": "475124309,1080176642"
}
],
"log_id": 1968648150
}相同图片搜索—更新
更新图库中图片的摘要和分类信息（具体变量为brief、tags）
Json::Value result;
std::string image;
aip::get_file_content("/assets/sample.jpg", &image);
// 调用相同图检索—更新, 图片参数为本地图片
result = client.same_hq_update(image, aip::null);
// 如果有可选参数
std::map<std::string, std::string> options;
options["brief"] = "{\"name\":\"周杰伦\", \"id\":\"666\"}";
options["tags"] = "100,11";
// 带参数调用相同图检索—更新, 图片参数为本地图片
result = client.same_hq_update(image, options);
Json::Value result;
std::string url = "http//www.x.com/sample.jpg";
// 调用相同图检索—更新, 图片参数为远程url图片
result = client.same_hq_update_url(url, aip::null);
// 如果有可选参数
std::map<std::string, std::string> options;
options["brief"] = "{\"name\":\"周杰伦\", \"id\":\"666\"}";
options["tags"] = "100,11";
// 带参数调用相同图检索—更新, 图片参数为远程url图片
result = client.same_hq_update_url(url, options);
Json::Value result;
std::string cont_sign = "8cnn32frvrr2cd901";
// 调用相同图检索—更新, 图片参数为图片签名
result = client.same_hq_update_cont_sign(cont_sign, aip::null);
// 如果有可选参数
std::map<std::string, std::string> options;
options["brief"] = "{\"name\":\"周杰伦\", \"id\":\"666\"}";
options["tags"] = "100,11";
// 带参数调用相同图检索—更新, 图片参数为图片签名
result = client.same_hq_update_cont_sign(cont_sign, options);相同图片搜索—更新 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
| image | 否 | std::string | 图片数据的二进制字符串，可以使用aip::get_file_content函数获取。和url、cont_sign三选一，优先级：image > url > cont_sign |
| url | 否 | std::string | 图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少50px，最长边最大4096px；支持jpg/png/bmp格式，当image字段存在时url字段失效。由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传 |
| cont_sign | 否 | std::string | 图片签名，和image、url三选一，优先级：image > url > cont_sign；不支持批量传入签名，样例："932301884,10680062193" |
| brief | 否 | std::string | 更新的摘要信息，最长256B。样例：{"name":"周杰伦", "id":"666"} |
| tags | 否 | std::string | 1 - 65535范围内的整数，tag间以逗号分隔，最多2个tag。样例："100,11" ；检索时可圈定分类维度进行检索 |
相同图片搜索—更新 返回数据参数详情
| 字段 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
| log_id | 是 | uint64 | 唯一的log id，用于问题定位 |
相同图片搜索—更新 返回示例
{
"log_id": 2263663554
}相同图片搜索—删除
删除图库中的图片，支持批量删除，批量删除时请传cont_sign参数，勿传image、url，最多支持1000个cont_sign。
图片删除延时生效，每天数据库定时更新进行物理删除，刚删除时仍然可以在图库中检索到（但图库管理后台是同步清除），请过一段时间再验证，一般最多延时4小时左右。
Json::Value result;
std::string image;
aip::get_file_content("/assets/sample.jpg", &image);
// 调用删除相同图，传入参数为图片
result = client.same_hq_delete_by_image(image, aip::null);
Json::Value result;
std::string url = "http//www.x.com/sample.jpg";
// 调用删除相同图，图片参数为远程url图片
result = client.same_hq_delete_by_url(url, aip::null);
Json::Value result;
std::string cont_sign = "8cnn32frvrr2cd901";
// 调用删除相同图，传入参数为图片签名
result = client.same_hq_delete_by_sign(cont_sign, aip::null);相同图片搜索—删除 请求参数详情
| 参数名称 | 是否必选 | 类型 | 说明 |
|---|---|---|---|
| image | 是 | std::string | 图片数据的二进制字符串，可以使用aip::get_file_content函数获取。和url、cont_sign三选一，优先级：image > url > cont_sign |
| url | 是 | std::string | 图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少50px，最长边最大4096px。支持jpg/png/bmp格式，当image字段存在时url字段失效。和image、cont_sign三选一，image优先级更高。由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传 |
| cont_sign | 是 | std::string | 图片签名（和image、url三选一），支持批量删除，批量删除时请勿传image、url，最多支持1000个cont_sign列表，样例："932301884,1068006219;316336521,553141152;2491030726,1352091083" |
相同图片搜索—删除 返回数据参数详情
| 参数 | 类型 | 是否必须 | 说明 | 示例 |
|---|---|---|---|---|
| log_id | number | 是 | 请求标识码，随机数，唯一 | 507499361 |
相同图片搜索—删除 返回示例
{
"log_id": 50488417
}