接口说明

更新时间：2022-11-15

相同图片搜索

在自建库中搜索相同图片，仅返回完全相同或局部相同的图片结果。

典型应用场景：图片去重、图片精确查找，如图片类站点对海量库存图片进行查重过滤
适用的图片类型：各种网络图片、实拍图均可；注意检索图和入库的原图要保持场景一致性，比如入库的原图为标准的广告图（无背景干扰），则检索图要尽量避免背景、其他干扰特征，否则模型计算图片的相似度时会有噪声，造成检索结果不准确。

举个例子：小张入库了5万张海报设计图，都是标准的电子版海报图片，无任何背景干扰；在线下活动时，要根据手机拍摄的海报图片判断是不是跟图库里的设计图重复了，手机实拍时要避免拍到海报图片之外的物体（如墙上的装饰、参加活动的人等各种背景元素），同时要拍到海报的全部或者大部分主体内容，不能只拍到一个海报的小角落就去检索，以免影响检索效果。

相同图片搜索包含入库、检索、删除、更新4个子接口；在正式使用之前请在控制台创建应用后，在应用详情页申请建库，建库成功后方可正常使用入库、检索、删除、更新接口。

申请建库时，图库的图片数量上限为50万，避免浪费资源；如果容量不够用，可在控制台-应用详情页申请扩容，工作人员会在1-3个工作日内审批，每次扩容的申请上限也是50万，可以反复申请扩容，原则上图库总量无上限，百万级、千万级、甚至亿级的图片量都可以做到实时检索，秒级返回检索结果。

相同图片搜索—入库

该接口实现单张图片入库，入库时需要同步提交图片及可关联至本地图库的摘要信息（具体变量为brief，具体可传入图片在本地标记id、图片url、图片名称等）；同时可提交分类维度信息（具体变量为tags，最多可传入2个tag），方便对图库中的图片进行管理、分类检索。

注：重复添加完全相同的图片会返回错误。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("tags", "100,11");
    
    String brief = "{\"name\":\"周杰伦\", \"id\":\"666\"}";
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.sameHqAdd(image, brief, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.sameHqAdd(file, brief, options);
    System.out.println(res.toString(2));
    
    // 相同图检索—入库, 图片参数为远程url图片
    JSONObject res = client.sameHqAddUrl(url, brief, options);
    System.out.println(res.toString(2));

}

相同图片搜索—入库请求参数详情

参数名称	是否必选	类型	说明
image	是	mixed	本地图片路径或者图片二进制数据。重复添加完全相同的图片会返回错误，提示不能重复入库
url	是	String	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少50px，最长边最大4096px,支持jpg/png/bmp格式，当image字段存在时url字段失效。由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传
brief	是	String	检索时原样带回,最长256B。样例：{"name":"周杰伦", "id":"666"} 。请注意，检索接口不返回原图，仅返回入库时填写的brief信息，所以调用入库接口时，brief信息请尽量填写可关联至本地图库的图片id或者图片url、图片名称等信息
tags	否	String	1 - 65535范围内的整数，tag间以逗号分隔，最多2个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等信息。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("tags", "100,11");
    options.put("tag_logic", "0");
    options.put("pn", "100");
    options.put("rn", "250");
    
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.sameHqSearch(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.sameHqSearch(file, options);
    System.out.println(res.toString(2));
    
    // 相同图检索—检索, 图片参数为远程url图片
    JSONObject res = client.sameHqSearchUrl(url, options);
    System.out.println(res.toString(2));

}

相同图片搜索—检索请求参数详情

参数名称	是否必选	类型	说明
image	是	mixed	本地图片路径或者图片二进制数据
url	是	String	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少50px，最长边最大4096px,支持jpg/png/bmp格式，当image字段存在时url字段失效。由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传
tags	否	String	1 - 65535范围内的整数，tag间以逗号分隔，最多2个tag。样例："100,11"
tag_logic	否	String	检索时tag之间的逻辑， 0：逻辑and，1：逻辑or
pn	否	String	分页功能，起始位置，例：0。未指定分页时，默认返回前300个结果；接口返回数量最大限制1000条，例如：起始位置为900，截取条数500条，接口也只返回第900 - 1000条的结果，共计100条
rn	否	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）

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("brief", "{\"name\":\"周杰伦\", \"id\":\"666\"}");
    options.put("tags", "100,11");
    
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.sameHqUpdate(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.sameHqUpdate(file, options);
    System.out.println(res.toString(2));
    
    // 相同图检索—更新, 图片参数为远程url图片
    JSONObject res = client.sameHqUpdateUrl(url, options);
    System.out.println(res.toString(2));
    
    
    // 相同图检索—更新,根据签名更新
    String contSign = "8cnn32frvrr2cd901";
    JSONObject res = client.sameHqUpdateContSign(contSign, options);
    System.out.println(res.toString(2));
    

}

相同图片搜索—更新请求参数详情

参数名称	是否必选	类型	说明
image	是	mixed	本地图片路径或者图片二进制数据
url	是	String	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少50px，最长边最大4096px,支持jpg/png/bmp格式，当image字段存在时url字段失效
brief	否	String	更新的摘要信息，最长256B。样例：{"name":"周杰伦", "id":"666"}
tags	否	String	1 - 65535范围内的整数，tag间以逗号分隔，最多2个tag。样例："100,11" ；检索时可圈定分类维度进行检索

相同图片搜索—更新返回数据参数详情

字段	是否必选	类型	说明
log_id	是	uint64	唯一的log id，用于问题定位

相同图片搜索—更新返回示例

{
    "log_id": 2263663554
}

相同图片搜索—删除

删除图库中的图片，支持批量删除，批量删除时请传cont_sign参数，勿传image，最多支持100个cont_sign。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.sameHqDeleteByImage(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.sameHqDeleteByImage(file, options);
    System.out.println(res.toString(2));
    
    // 删除相同图，图片参数为远程url图片
    JSONObject res = client.sameHqDeleteByUrl(url, options);
    System.out.println(res.toString(2));

    
    // 删除相同图，传入参数为图片签名
    JSONObject res = client.sameHqDeleteBySign(contSign, options);
    System.out.println(res.toString(2));

}

相同图片搜索—删除请求参数详情

参数名称	是否必选	类型	说明
image	是	mixed	本地图片路径或者图片二进制数据
url	是	String	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少50px，最长边最大4096px,支持jpg/png/bmp格式，当image字段存在时url字段失效
cont_sign	是	String	图片签名（和image、url三选一），支持批量删除，批量删除时请勿传image、url，最多支持100个cont_sign列表，样例："932301884,1068006219;316336521,553141152;2491030726,1352091083"

相同图片搜索—删除返回数据参数详情

参数	类型	是否必须	说明	示例
log_id	number	是	请求标识码，随机数，唯一	507499361

相同图片搜索—删除返回示例

{
  "log_id": 50488417
}

相似图片搜索

在自建图库中找到与检索图片语义相似的图片集，并给出相似度打分（综合图片类型、颜色、内容、布局等特征）

典型应用场景：找相似的图片集合（返回的结果包含相同的图片），各种设计素材、美术作品、UGC内容等
适用的图片类型：各种网络图片、实拍图均可；注意检索图和入库的原图要尽量保持场景一致性，比如入库的原图为标准的广告图（无背景干扰），则检索图要尽量避免背景、其他干扰特征，否则模型计算图片的相似度时会有噪声，造成检索结果不准确。

相似图片搜索包含入库、检索、删除、更新4个子接口；在正式使用之前请在控制台创建应用后，在应用详情页申请建库，建库成功后方可正常使用入库、检索、删除、更新接口。

相似图片搜索—入库

注：重复添加完全相同的图片会返回错误。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("tags", "100,11");
    
    String brief = "{\"name\":\"周杰伦\", \"id\":\"666\"}";
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.similarAdd(image, brief, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.similarAdd(file, brief, options);
    System.out.println(res.toString(2));
    
    // 相似图检索—入库, 图片参数为远程url图片
    JSONObject res = client.similarAddUrl(url, brief, options);
    System.out.println(res.toString(2));

}

相似图片搜索—入库请求参数详情

参数名称	是否必选	类型	说明
image	是	mixed	本地图片路径或者图片二进制数据。重复添加完全相同的图片会返回错误，提示不能重复入库。
url	是	String	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少50px，最长边最大4096px,支持jpg/png/bmp格式，当image字段存在时url字段失效。由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传
brief	是	String	检索时原样带回,最长256B。样例：{"name":"周杰伦", "id":"666"} 。请注意，检索接口不返回原图，仅返回入库时填写的brief信息，所以调用该入库接口时，brief信息请尽量填写可关联至本地图库的图片id或者图片url、图片名称等信息
tags	否	String	1 - 65535范围内的整数，tag间以逗号分隔，最多2个tag，无层级关系。样例："100,11" ；检索时可圈定分类维度进行检索

相似图片搜索—入库返回数据参数详情

字段	是否必选	类型	说明
log_id	是	uint64	唯一的log id，用于问题定位
cont_sign	是	string	输入图片的签名信息，请务必保存至本地，以便后续用作批量删除、查询某张图是否已经入过库等用途

相似图片搜索—入库返回示例

{
    "log_id": 2263663554,
    "cont_sign": "4261577168,501945506"
}

入库之后的图片，可在控制台的图库管理后台进行可视化管理，支持预览大图、更新摘要、更新分类信息、删除图片，入口在控制台-应用详情页管理图库，注：大批量更新摘要或分类、删除图片请调用API。

同时，图库管理后台支持在线测试检索效果，点击右上角搜索框边上的“相机”标识，可以上传图片，测试检索效果。

相似图片搜索—检索

完成入库后，可使用该接口实现相似图检索。支持传入指定分类维度（具体变量tags）进行检索，返回结果支持翻页（具体变量pn、rn）。

注意： 1、检索接口不返回原图，仅反馈入库时填写的brief信息，请调用入库接口时尽量填写可关联至本地图库的图片id或者图片url等信息。

2、检索接口默认返回TOP 300的结果，如果图库里不满300张图片，会返回所有图片，请入库足量图片以便充分测试效果。

3、原则上任何2张图片都有相似度，只不过分值有高低，应用时可结合接口返回的相关性分数score（取值范围0-1，越接近1代表相似度越高）进行筛选，如选取score大于某个值的结果进行应用。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("tags", "100,11");
    options.put("tag_logic", "0");
    options.put("pn", "100");
    options.put("rn", "250");
    
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.similarSearch(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.similarSearch(file, options);
    System.out.println(res.toString(2));
    
    // 相似图检索—检索, 图片参数为远程url图片
    JSONObject res = client.similarSearchUrl(url, options);
    System.out.println(res.toString(2));

}

相似图片搜索—检索请求参数详情

参数名称	是否必选	类型	说明
image	是	mixed	本地图片路径或者图片二进制数据
url	是	String	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少50px，最长边最大4096px,支持jpg/png/bmp格式，当image字段存在时url字段失效。由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传
tags	否	String	1 - 65535范围内的整数，tag间以逗号分隔，最多2个tag。样例："100,11" ；检索时可圈定分类维度进行检索
tag_logic	否	String	检索时tag之间的逻辑， 0：逻辑and，1：逻辑or
pn	否	String	分页功能，起始位置，例：0。未指定分页时，默认返回前300个结果；接口返回数量最大限制1000条，例如：起始位置为900，截取条数500条，接口也只返回第900 - 1000条的结果，共计100条
rn	否	String	分页功能，截取条数，例：250

相似图片搜索—检索返回数据参数详情

字段	是否必选	类型	说明
log_id	是	uint64	唯一的log id，用于问题定位
result_num	是	uint32	检索结果数
result	是	object[]	结果数组
+cont_sign	是	string	图片签名，可以用来删除图片或定位问题
+score	是	float	图片相关性，取值范围0-1，越接近1代表越相似
+brief	是	string	入库时添加的brief信息
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）。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("brief", "{\"name\":\"周杰伦\", \"id\":\"666\"}");
    options.put("tags", "100,11");
    
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.similarUpdate(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.similarUpdate(file, options);
    System.out.println(res.toString(2));
    
    // 相似图检索—更新, 图片参数为远程url图片
    JSONObject res = client.similarUpdateUrl(url, options);
    System.out.println(res.toString(2));

    // 相似图检索—更新, 根据签名更新
    String contSign = "8cnn32frvrr2cd901";
    JSONObject res = client.similarUpdateContSign(contSign, options);
    System.out.println(res.toString(2));
}

相似图片搜索—更新请求参数详情

参数名称	是否必选	类型	说明
image	是	mixed	本地图片路径或者图片二进制数据
url	是	String	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少50px，最长边最大4096px,支持jpg/png/bmp格式，当image字段存在时url字段失效。
cont_sign	否	string	图片签名，和image、url三选一，优先级：image > url > cont_sign；不支持批量传入签名，样例："932301884,10680062193"
brief	否	String	更新的摘要信息，最长256B。样例：{"name":"周杰伦", "id":"666"}
tags	否	String	1 - 65535范围内的整数，tag间以逗号分隔，最多2个tag。样例："100,11" ；检索时可圈定分类维度进行检索

相似图片搜索—更新返回数据参数详情

字段	是否必选	类型	说明
log_id	是	uint64	唯一的log id，用于问题定位

相似图片搜索—更新返回示例

{
    "log_id": 2263663554
}

相似图片搜索—删除

删除图库中的图片，支持批量删除，批量删除时请传cont_sign参数，勿传image，最多支持100个cont_sign。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.similarDeleteByImage(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.similarDeleteByImage(file, options);
    System.out.println(res.toString(2));
    
    // 删除相似图，图片参数为远程url图片
    JSONObject res = client.similarDeleteByUrl(url, options);
    System.out.println(res.toString(2));

    
    // 删除相似图，传入参数为图片签名
    JSONObject res = client.similarDeleteBySign(contSign, options);
    System.out.println(res.toString(2));

}

相似图片搜索—删除请求参数详情

参数名称	是否必选	类型	说明
image	是	mixed	本地图片路径或者图片二进制数据。和url、cont_sign三选一，优先级：image > url > cont_sign
url	是	String	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少15px，最长边最大4096px,支持jpg/png/bmp格式，当image字段存在时url字段失效。
cont_sign	是	String	图片签名（和image、url三选一），支持批量删除，批量删除时请勿传image、url，最多支持100个cont_sign列表。样例："932301884,1068006219;316336521,553141152;2491030726,1352091083"

相似图片搜索—删除返回数据参数详情

参数	类型	是否必须	说明	示例
log_id	number	是	请求标识码，随机数，唯一	507499361

相似图片搜索—删除返回示例

{
  "log_id": 50488417
}

商品图片搜索

针对商品类图片，专项训练检索模型，在自建图库中搜索相同及相似的商品图片集，可找到不同颜色、背景、角度的同款商品。

典型应用场景：各类B2B、B2C电商平台，相似商品推荐、拍照搜同款或者相似商品
适用的图片类型：电商商品图片（实体商品为主，如数码3C、服装鞋帽、日化百货等）

注意：部分特殊商品，如面料、木材、瓷砖等，建议同步对比测试相似图搜索的效果，择优使用。

商品图片搜索包含入库、检索、删除、更新4个子接口；在正式使用之前请在控制台创建应用后，在应用详情页申请建库，建库成功后方可正常使用入库、检索、删除、更新接口。

商品图片搜索—入库

该接口实现单张图片入库，入库时需要同步提交图片及可关联至本地图库的摘要信息（具体变量为brief，具体可传入图片在本地标记id、图片url、图片名称等）。同时可提交分类维度信息（具体变量为class_id1、class_id2），方便对图库中的图片进行管理、分类检索。

注：重复添加完全相同的图片会返回错误。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("class_id1", "1");
    options.put("class_id2", "1");
    
    String brief = "{\"name\":\"手机\", \"id\":\"666\"}";
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.productAdd(image, brief, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.productAdd(file, brief, options);
    System.out.println(res.toString(2));
    
    // 商品检索—入库, 图片参数为远程url图片
    JSONObject res = client.productAddUrl(url, brief, options);
    System.out.println(res.toString(2));

}

商品图片搜索—入库请求参数详情

参数名称	是否必选	类型	说明
image	是	mixed	本地图片路径或者图片二进制数据。和url二选一，image优先级更高。重复添加会返回错误。
url	是	String	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少300px，最长边最大4096px，支持jpg/png/bmp格式，当image字段存在时url字段失效。由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传
brief	是	String	检索时原样带回,最长256B。样例{"name":"周杰伦", "id":"666"} 。请注意，检索接口不返回原图，仅反馈当前填写的brief信息，所以调用该入库接口时，brief信息请尽量填写可关联至本地图库的图片id或者图片url、图片名称等信息
class_id1	否	String	商品分类维度1，支持1-65535范围内的整数。检索时可圈定该分类维度进行检索
class_id2	否	String	商品分类维度1，支持1-65535范围内的整数。检索时可圈定该分类维度进行检索

商品图片搜索—入库返回数据参数详情

字段	是否必选	类型	说明
log_id	是	uint64	唯一的log id，用于问题定位
cont_sign	是	string	上传图片的签名信息，请务必保存至本地，以便后续用作批量删除、查询某张图是否已经入过库等用途

商品图片搜索—入库返回示例

{
    "log_id": 2263663554,
    "cont_sign": "4261577168,501945506"
}

同时，图库管理后台支持在线测试检索效果，点击右上角搜索框边上的“相机”标识，可以上传图片，测试检索效果。

商品图片搜索—检索

完成入库后，可使用该接口实现相似商品图片检索。支持传入指定分类维度（具体变量class_id1、class_id2）进行检索，返回结果支持翻页（具体变量pn、rn）。

注意： 1、检索接口不返回原图，仅反馈入库时填写的brief信息，请调用入库接口时尽量填写可关联至本地图库的图片id或者图片url等信息。

2、检索接口默认返回TOP 300的结果，如果图库里不满300张图片，会返回所有图片，请入库足量图片以便充分测试效果。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("class_id1", "1");
    options.put("class_id2", "1");
    options.put("pn", "100");
    options.put("rn", "250");
    
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.productSearch(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.productSearch(file, options);
    System.out.println(res.toString(2));
    
    // 商品检索—检索, 图片参数为远程url图片
    JSONObject res = client.productSearchUrl(url, options);
    System.out.println(res.toString(2));

}

商品图片搜索—检索请求参数详情

参数名称	是否必选	类型	说明
image	是	mixed	本地图片路径或者图片二进制数据。和url二选一，image优先级更高
url	是	String	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少300px，最长边最大4096px,支持jpg/png/bmp格式，当image字段存在时url字段失效由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传
class_id1	否	String	商品分类维度1，支持1-65535范围内的整数。检索时可圈定该分类维度进行检索
class_id2	否	String	商品分类维度1，支持1-65535范围内的整数。检索时可圈定该分类维度进行检索
tag_logic	否	String	检索时tag之间的逻辑， 0：逻辑and，1：逻辑or
pn	否	String	分页功能，起始位置，例：0。未指定分页时，默认返回前300个结果；接口返回数量最大限制1000条，例如：起始位置为900，截取条数500条，接口也只返回第900 - 1000条的结果，共计100条
rn	否	String	分页功能，截取条数，例：250

商品图片搜索—检索返回数据参数详情

字段	是否必选	类型	说明
log_id	是	uint64	唯一的log id，用于问题定位
result_num	是	uint32	检索结果数
result	是	object[]	结果数组
+cont_sign	是	string	图片签名，可以用来删除图片或定位问题
+score	是	float	图片相关性，取值范围0-1，越接近1代表越相似
+brief	是	string	入库时添加的brief信息
has_more	是	bool	是否还有下一页，返回值：true、false；如果不分页，不用关注该字段

商品图片搜索—检索返回示例

{
    "result_num": 1,
    "result": [
        {
            "score": 0.97976700290421,
            "brief": "./data/mobile.jpg",
            "cont_sign": "475124309,1080176642"
        }
    ],
    "log_id": 1968648150
}

商品图片搜索—更新

更新图库中图片的摘要和分类信息（具体变量为brief、class_id1/class_id2）。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("brief", "{\"name\":\"周杰伦\", \"id\":\"666\"}");
    options.put("class_id1", "1");
    options.put("class_id2", "1");
    
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.productUpdate(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.productUpdate(file, options);
    System.out.println(res.toString(2));
    
    // 商品检索—更新, 图片参数为远程url图片
    JSONObject res = client.productUpdateUrl(url, options);
    System.out.println(res.toString(2));

}

商品图片搜索—更新请求参数详情

参数名称	是否必选	类型	说明
image	是	mixed	本地图片路径或者图片二进制数据
url	是	String	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少300px，最长边最大4096px,支持jpg/png/bmp格式，当image字段存在时url字段失效
cont_sign	否	string	图片签名，和image、url三选一，优先级：image > url > cont_sign；不支持批量传入签名，样例："932301884,10680062193"
brief	否	String	更新的摘要信息，最长256B。样例：{"name":"周杰伦", "id":"666"}
class_id1	否	String	更新的商品分类1，支持1-65535范围内的整数。
class_id2	否	String	更新的商品分类2，支持1-65535范围内的整数。

商品图片搜索—更新返回数据参数详情

字段	是否必选	类型	说明
log_id	是	uint64	唯一的log id，用于问题定位

商品图片搜索—更新返回示例

{
    "log_id": 2263663554
}

商品图片搜索—删除

删除图库中的图片，支持批量删除，批量删除时请传cont_sign参数，勿传image，最多支持100个cont_sign。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.productDeleteByImage(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.productDeleteByImage(file, options);
    System.out.println(res.toString(2));
    
    // 删除商品，图片参数为远程url图片
    JSONObject res = client.productDeleteByUrl(url, options);
    System.out.println(res.toString(2));

    
    // 删除商品，传入参数为图片签名
    JSONObject res = client.productDeleteBySign(contSign, options);
    System.out.println(res.toString(2));

}

商品图片搜索—删除请求参数详情

参数名称	是否必选	类型	说明
image	是	mixed	本地图片路径或者图片二进制数据。（和url、cont_sign三选一，优先级：image > url > cont_sign）
url	是	String	图片完整URL，URL长度不超过1024字节，URL对应的图片base64编码后大小不超过4M，最短边至少300px，最长边最大4096px，支持jpg/png/bmp格式，当image字段存在时url字段失效。由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传
cont_sign	是	String	图片签名（和image、url三选一，优先级最低），支持批量删除，批量删除时请勿传image、url，最多支持100个cont_sign列表，样例："932301884,1068006219;316336521,553141152;2491030726,1352091083"

商品图片搜索—删除返回数据参数详情

参数	类型	是否必须	说明	示例
log_id	number	是	请求标识码，随机数，唯一	507499361

商品图片搜索—删除返回示例

{
  "log_id": 50488417
}

绘本图片搜索—入库

该接口实现单张图片入库，入库时需要同步提交图片及可关联至本地图库的摘要信息（具体变量为brief，具体可传入图片在本地标记id、图片url、图片名称等）；同时可提交分类维度信息（具体变量为tags，最多可传入2个tag），方便对图库中的图片进行管理、分类检索。

注：重复添加完全相同的图片会返回错误。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("tags", "100,11");

    JSONObject brief = new JSONObject();
    brief.put("name", "周杰伦");
    brief.put("id", "566");

    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.pictureBookAddImage(image, brief, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.pictureBookAddImage(file, brief, options);
    System.out.println(res.toString(2));

    // 参数为远程url图片
    String url = "http//www.x.com/sample.jpg";
    res = client.pictureBookAddUrl(url, brief, options);
    System.out.println(res.toString(2));
}

绘本图片搜索—入库请求参数详情

参数	是否必选	类型	可选值范围	说明
image	否	string	-	图像数据，base64编码后进行urlencode，要求base64编码和urlencode后大小不超过4M。（和url二选一，image优先级更高），注意要去掉图片头部，如`（data:image/jpg;base64,）`；最短边至少150px，最长边最大4096px，长宽比在1：10-10：1之间。支持jpg/png/bmp格式。重复添加完全相同的图片会返回错误，提示不能重复入库。
url	否	string	-	图片URL，和image二选一，image优先级更高，由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传
brief	是	string	-	检索时原样带回,最长256B。样例：{"name":"周杰伦", "id":"666"} 。请注意，检索接口不返回原图，仅返回入库时填写的brief信息，所以调用入库接口时，brief信息请尽量填写可关联至本地图库的图片id或者图片url、图片名称等信息
tags	否	string	1 - 65535范围内的整数	tag间以逗号分隔，最多2个tag，2个tag无层级关系，检索时支持逻辑运算。样例："100,11" ；检索时可圈定分类维度进行检索

绘本图片搜索—入库返回数据参数详情

字段	是否必选	类型	说明
log_id	是	uint64	唯一的log id，无实际意义，用于问题定位
cont_sign	是	string	入库图片的签名信息，请务必保存至本地，以便后续用作批量删除、查询某张图是否已经入过库等用途

绘本图片搜索—入库返回示例

{
    "log_id": 2263663554,
    "cont_sign": "4261577168,501945506"
}

绘本图片搜索—检索

完成入库后，可使用该接口实现绘本图检索。支持传入指定分类维度（具体变量tags）进行检索，返回结果支持翻页（具体变量pn、rn）。

请注意，检索接口不返回原图，仅反馈入库时填写的brief信息，请调用入库接口时尽量填写可关联至本地图库的图片id或者图片url等信息。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("tags", "100,11");
    options.put("tag_logic", "0");
    options.put("pn", "100");
    options.put("rn", "250");

    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.pictureBookSearchImage(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.pictureBookSearchImage(file, options);
    System.out.println(res.toString(2));

    // 参数为远程url图片
    String url = "http//www.x.com/sample.jpg";
    res = client.pictureBookSearchUrl(url, options);
    System.out.println(res.toString(2));
}

绘本图片搜索—检索请求参数详情

参数	是否必选	类型	可选值范围	说明
image	否	string	-	图像数据，base64编码后进行urlencode，要求base64编码和urlencode后大小不超过4M。（和url二选一，image优先级更高），注意要去掉图片头部，如`（data:image/jpg;base64,）`；最短边至少150px，最长边最大4096px，长宽比在1：10-10：1之间。支持jpg/png/bmp格式
url	否	string	-	图片URL，和image二选一，image优先级更高，由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传
tags	否	string	1 - 65535范围内的整数	分类维度信息，tag间以逗号分隔，最多可传入2个tag，tag间无层级关系，示例："100,11"
tag_logic	否	string	0,1	检索时tag之间的逻辑， 0：逻辑and，1：逻辑or
pn	否	string	0 - 999范围内的整数	分页功能，起始位置，例：0，代表从第1个结果开始。注：未指定分页时，默认返回前300个结果；接口返回数量最大限制1000个，例如：起始位置为900，截取条数500条，接口也只返回第901 - 1000条的结果，共计100条
rn	否	string	1 - 1000范围内的整数	分页功能，截取条数，例：250

绘本图片搜索—检索返回数据参数详情

字段	是否必选	类型	说明
log_id	是	uint64	唯一的log id，无实际含义，用于问题定位
result_num	是	uint32	检索结果数
result	是	object[]	结果数组
+cont_sign	是	string	入库图片签名，可以用来删除图片或定位问题
+score	是	float	图片相关性，取值范围0-1，越接近1表示越相关
+brief	是	string	调用入库add接口时添加的brief信息，为保证该结果有效性，请入库时填写可关联至本地图片库的有效id信息
has_more	是	bool	是否还有下一页，返回值：true、false；如果不分页，不用关注该字段

绘本图片搜索—检索返回示例

{
    "result_num": 1,
    "result": [
        {
            "score": 0.97976700290421,
            "brief": "./data/jay1.jpg",
            "cont_sign": "475124309,1080176642"
        }
    ],
	"has_more": "false",
    "log_id": 1968648150
}

绘本图片搜索—更新

更新图库中图片的摘要和分类信息（具体变量为brief、tags）。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    
    JSONObject brief = new JSONObject();
    brief.put("name", "周杰伦");
    brief.put("id", "566");

    options.put("brief", brief);
    options.put("tags", "100,11");

    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.pictureBookUpdate(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.pictureBookUpdate(file, options);
    System.out.println(res.toString(2));

    // 参数为远程url图片
    String url = "http//www.x.com/sample.jpg";
    res = client.pictureBookUpdateUrl(url, options);
    System.out.println(res.toString(2));

        // 参数为根据签名更新
    String contSign = "8cnn32frvrr2cd901";
    res = client.pictureBookUpdateContSign(contSign, options);
    System.out.println(res.toString(2));
}

绘本图片搜索—更新请求参数详情

参数	是否必选	类型	可选值范围	说明
image	否	string	-	图片数据，base64编码后进行urlencode，要求base64编码和urlencode后大小不超过4M，和url、cont_sign三选一，优先级：image > url > cont_sign，注意要去掉图片头部，如`（data:image/jpg;base64,）`，最短边至少150px，最长边最大4096px，长宽比在1：10-10：1之间。支持jpg/png/bmp格式
url	否	string	-	图片URL，和image、cont_sign三选一，优先级：image > url > cont_sign ，由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传
cont_sign	否	string	-	图片签名，和image、url三选一，优先级：image > url > cont_sign；不支持批量传入签名，样例："932301884,10680062193"
brief	否	string	-	更新的摘要信息，最长256B。样例：{"name":"周杰伦", "id":"666"}
tags	否	string	1 - 65535范围内的整数	更新的分类信息，tag间以逗号分隔，最多2个tag。样例："100,11"

绘本图片搜索—更新返回数据参数详情

字段	是否必选	类型	说明
log_id	是	uint64	唯一的log id，用于问题定位

绘本图片搜索—更新返回示例

{
    "log_id": 2263663554
}

绘本图片搜索—删除

删除图库中的图片，支持批量删除，批量删除时请传cont_sign参数，勿传image、url，最多支持100个cont_sign。

图片删除延时生效，每天数据库定时更新进行物理删除，刚删除时仍然可以在图库中检索到（但图库管理后台是同步清除），请过一段时间再验证，一般最多延时4小时左右。

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    JSONObject brief = new JSONObject();
    brief.put("name", "周杰伦");
    brief.put("id", "566");

    options.put("brief", brief);
    options.put("tags", "100,11");

    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.pictureBookDeleteByImage(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.pictureBookDeleteByImage(file, options);
    System.out.println(res.toString(2));

    // 参数为远程url图片
    String url = "http//www.x.com/sample.jpg";
    res = client.pictureBookDeleteByUrl(url, options);
    System.out.println(res.toString(2));

        // 参数为远程url图片
    String contSign = "8cnn32frvrr2cd901";
    res = client.pictureBookDeleteBySign(contSign, options);
    System.out.println(res.toString(2));
}

绘本图片搜索—删除请求参数详情

参数	是否必选	类型	可选值范围	说明
image	否	string	-	图片数据，base64编码后进行urlencode，要求base64编码和urlencode后大小不超过4M，（和url、cont_sign三选一，优先级：image > url > cont_sign），注意要去掉图片头部，如`（data:image/jpg;base64,）`。最短边至少150px，最长边最大4096px，长宽比在1：10-10：1之间。支持jpg/png/bmp格式
url	否	string	-	图片URL，和image、cont_sign三选一，image优先级更高，由于图床的差异性，抓图服务无法适配所有的图床，部分URL可能抓不到图，或者图片下载超时，遇到上述情况时请更换图片URL、或者将图片下载到本地转码后上传
cont_sign	否	string	-	图片签名（和image、url三选一），支持批量删除，批量删除时请勿传image、url，最多支持100个cont_sign列表，样例："932301884,1068006219;316336521,553141152;2491030726,1352091083"

绘本图片搜索—删除返回数据参数详情

字段	是否必选	类型	说明
log_id	是	uint64	唯一的log id，用于问题定位

绘本图片搜索—删除返回示例

{
  "log_id": 50488417
}

面料图片搜索

面料图片搜索—入库

SDK 调用示例

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("tags", "100,11");
    
    String brief = "{\"name\":\"周杰伦\", \"id\":\"666\"}";
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.materielAdd(image, brief, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.materielAdd(file, brief, options);
    System.out.println(res.toString(2));
    
    // 面料图片搜索—入库, 图片参数为远程url图片
    JSONObject res = client.materielAddUrl(url, brief, options);
    System.out.println(res.toString(2));

}

接口详情

可参考API文档：面料图片搜索—入库

面料图片搜索—检索

SDK 调用示例

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("tags", "100,11");
    options.put("tag_logic", "0");
    options.put("pn", "100");
    options.put("rn", "250");
    
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.materielSearch(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.materielSearch(file, options);
    System.out.println(res.toString(2));
    
    // 面料图片搜索—检索, 图片参数为远程url图片
    JSONObject res = client.materielSearchUrl(url, options);
    System.out.println(res.toString(2));

}

接口详情

可参考API文档：面料图片搜索—检索

面料图片搜索—更新

SDK 调用示例

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    options.put("brief", "{\"name\":\"周杰伦\", \"id\":\"666\"}");
    options.put("tags", "100,11");
    
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.materielUpdate(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.materielUpdate(file, options);
    System.out.println(res.toString(2));
    
    // 面料图片搜索—更新, 图片参数为远程url图片
    String url = "http//www.x.com/sample.jpg";
    JSONObject res = client.materielUpdateUrl(url, options);
    System.out.println(res.toString(2));
    
    
    // 面料图片搜索—更新,根据签名更新
    String contSign = "8cnn32frvrr2cd901";
    JSONObject res = client.materielUpdateContSign(contSign, options);
    System.out.println(res.toString(2));

}

接口详情

可参考API文档：面料图片搜索—更新

面料图片搜索—删除

SDK 调用示例

public void sample(AipImageSearch client) {
    // 传入可选参数调用接口
    HashMap<String, String> options = new HashMap<String, String>();
    
    
    // 参数为本地路径
    String image = "test.jpg";
    JSONObject res = client.materielDeleteByImage(image, options);
    System.out.println(res.toString(2));

    // 参数为二进制数组
    byte[] file = readFile("test.jpg");
    res = client.materielDeleteByImage(file, options);
    System.out.println(res.toString(2));
    
    // 删除面料图片，图片参数为远程url图片
	  String url = "http//www.x.com/sample.jpg";
    JSONObject res = client.materielDeleteByUrl(url, options);
    System.out.println(res.toString(2));

    
    // 删除面料图片，传入参数为图片签名
    String contSign = "8cnn32frvrr2cd901";
    JSONObject res = client.materielDeleteBySign(contSign, options);
    System.out.println(res.toString(2));

}

接口详情

可参考API文档：面料图片搜索—删除

快速入门

常见问题