拍照购
一、接口描述
1. 功能描述
拍照购(Snapshop)API提供商品搜索的图像检索方案:识别图像中的商品,经过处理,返回与图片中某一主体视觉相似的商品列表。
2. 能力说明:
当前可以检索如下类目的商品:裙装、上衣、下衣、鞋靴、箱包、数码家电、食品饮料、玩具乐器、配饰、个护洗化、家居家装、手机、图书影音、绿植。
3. 接口数据要求:
- 图片格式:Base64 (JPEG/JPG/BMP)
- 图片像素:最小 128*128
- 图片大小:小于 3.75M
4. 接口使用:
平台为每个API提供试用体验服务,您在AI市场选择“免费试用”规格下单后,即可开始体验业内领先的人工智能API服务。 免费试用服务具有调用量、QPS限制,如需更高性能的API服务,可以提交咨询工单,联系京东AI扩容购买。
在获得使用权限后,您可使用已经封装好的SDK/参照接口鉴权规则进行相应开发,整体流程详见 接入流程
二、请求说明
1. 接口地址 :
https://aiapi.jd.com/jdai/snapshop
2. 请求方式:
post
3. 请求参数
(1)query请求参数
公共请求参数
名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
appkey | String | 是 | 80d2b762ecb86593f9668526920f46c | 您的appkey,可在买家中心控制台中获取 |
timestamp | long | 是 | 1541491668060 | 请求的时间戳,精确到毫秒,timestamp有效期5分钟 |
sign | String | 是 | 2e148773a0337a8f2200ba90d445f083 | 签名,根据规则MD5(sectetkey+timestamp), |
(2)header请求参数
业务请求参数
名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
Content-Type | String | 是 | text/plain | 标准编码格式 |
(3)body请求参数
业务请求参数
首次请求参数
imgBase64=xxx&channel_id=test&topK=50&multi_bboxes=true&skip_detect=false
其中,各参数定义如下
名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
imgBase64 | String | 是 | 图像Base64编码值,去掉图片头"data:image/png;base64,", imgBase64=iVBORw0K...(由于过长,不给出示例) |
图片base64编码 |
channel_id | String | 是 | channel_id=test | 业务方识别码 |
topK | int | 否 | topK=50 | 返回商品列表个数(默认为50) |
multi_bboxes | bool | 否 | multi_bboxes=true | 是否返回多个检测框商品 |
skip_detect | bool | 否 | skip_detect=false | true: 使用输入图像直接进行商品召回; false: 使用拍照购检测流程 |
触发请求参数(测试接口暂不提供此功能)
imgBase64=xxx&channel_id=test&topK=50&action_type=0&main_category_list=300|1|2|0|7|10|8|4|6|9|3|5|14|13|11|12&main_category_id=2&main_body_rectangle=10,10|700,700
其中,各参数定义如下
名称 | 类型 | 必填 | 示例值 | 描述 |
---|---|---|---|---|
imgBase64 | String | 是 | 图像Base64编码值,去掉图片头"data:image/png;base64,", imgBase64=iVBORw0K...( 由于过长,不给出示例) |
图片base64编码 |
channel_id | String | 是 | channel_id=xxxx | 业务方识别码 |
topK | int | 否 | topK=50 | 返回商品列表个数(默认为50) |
action_type | int | 是 | action_type=0 | 输入可选0或者1, 操作选择 0:切换类目 1:重新框选 |
main_category_list | String | action_type=0情况下必填 | main_category_list= 300|1|2|0|7|10|8|4|6|9| 3|5|14|13|11|12 |
类目相似度排序(由首次请求返回结果获得) |
main_category_id | int | action_type=0情况下必填 | main_category_id=2 | 待切换到类目的id |
main_body_rectangle | String | action_type=1情况下必填 | main_body_rectangle= 10,10|700,900 |
重新框选区域位置,结构为:左上角坐标x值(left),左上角坐标y值(top)|右下角坐标x值(right),右下角坐标y值(bottom).注意,left以及top值最小值为1,right最大值为宽度-1,bottom最大值为高度-1. |
注意:1.若无action_type字段,用户触发请求无效; 2.channel_id=test 每日最大调用量为500次
4、请求代码示例
建议您使用我们提供的SDK进行调用,SDK获取及调用方式详见本页一接口描述中的4接口使用
三、返回说明
1、返回参数
(1)公共返回参数
名称 | 类型 | 示例值 | 描述 |
---|---|---|---|
code | string | 1000 | 参见下方错误码-系统级错误码 |
charge | boolean | false 或 true | false:不扣费, true:扣费 |
remainTimes | long | 1305 | 剩余调用次数;免费api:每天剩余调用次数;收费api:剩余次数;无限制时为-1 |
remainSeconds | long | 1223456 | 剩余调用时间(s);免费api:-1;收费api:剩余调用时间;无限制时为-1 |
msg | string | 查询成功 | 参见下方错误码-系统级错误码 |
result | object | {...} | 查询结果 |
(2)业务返回参数
result参数信息
名称 | 类型 | 示例值 | 描述 |
---|---|---|---|
status | int | 0 | 参照四、错误码-业务错误码 |
message | string | "Interface Succeed!" | 参照四、错误码-业务错误信息 |
channel_id | string | "test" | 业务方识别码(与输入相同) |
query_id | string | "bd65b0d0541f4b2c729a08e7bf123ff7" | 用户请求query唯一标识字段 |
main_category_list | string | 300|1|2|0|7|10|8|4|6|9|3|5|14|13|11|12 | 类目预测排序,根据分类置信度排序 |
main_category_names | string | 全部|上衣|下衣|裙装|玩具乐器|家居家装|配饰|箱包| 食品饮料|个护洗化|鞋靴|数码家电|其他|绿植|手机|图书影音 |
与类目列表对应的中文名称 |
img_width | int | 1280 | 图像宽度 |
img_height | int | 800 | 图像高度 |
dataValue | object | {...} | 返回商品信息 |
dataValue参数信息
名称 | 类型 | 示例值 | 描述 |
---|---|---|---|
rectangle | object | {...} | 商品框和商品类目信息 |
sims | array | [...] | 相似商品列表信息 |
rectangle参数信息
名称 | 类型 | 示例值 | 描述 |
---|---|---|---|
bottom | string | 986.351 | 商品框下方值(右下角坐标y值) |
cls | int | 300 | 类目信息 |
clsName | string | "全部" | 返回结果类目中文名称 |
isUserRectangle | int | 0 | 是否是用户框选(暂不支持) |
left | string | "305.181" | 商品框左侧值(左上角坐标x值) |
right | string | "410.498" | 商品框右侧值(右下角坐标x值) |
top | string | "12.641" | 商品框上方值(左上角坐标y值) |
sims参数信息
名称 | 类型 | 示例值 | 描述 |
---|---|---|---|
cls | int | 300 | 返回结果类目信息 |
clsName | string | "全部" | 返回结果类目中文名称 |
cid1Name | string | "家具" | 返回结果一级类目中文名称 |
cid2Name | string | "客厅家具" | 返回结果二级类目中文名称 |
cid3Name | string | "鞋柜" | 返回结果三级类目中文名称 |
detailUrl | string | "http://item.jd.com/30149050873.html" | 商品详情页信息(JD.COM) |
detailAppUrl | string | "http://item.m.jd.com/product/30149050873.html" | APP端商品详情页 |
dis | float | 1.22123921 | 商品图与用户上传图像相似度距离 |
similarity | float | 0.687317 | 商品图与用户上传图像相似度 |
imageUrl | string | "http://img14..."(页面原因未全部展示) | 商品主图jfs地址 |
allImageUrls | array | ["http://img14...", "http://img14..."\] | 商品所有主辅图图片地址 |
skuId | unsigned long | 30149050873 | 商品sku ID |
skuName | string | "鞋柜简约现代经济型鞋门厅柜 组装 北欧玄关柜柚木色两门高组装" |
商品名称 |
skuPrice | string | "123.00" | 商品价格 |
wareLabel | string | "自营" | 有自营/非自营/京东物流/京东精选 四种商品销售渠道可供选择 |
2、返回示例
"code": "10000",
"charge": false,
"remain": 0,
"remainTimes": -1,
"remainSeconds": -1,
"msg": "查询成功",
"result": {
"channel_id": "test",
"dataValue": [
{
"rectangle": {
"bottom": "658.029785",
"cls": 300,
"clsName": "全部",
"isUserRectangle": 0,
"left": "272.751526",
"right": "551.015198",
"top": "220.425461"
},
"sims": [
{
"cls": 300,
"clsName": "全部",
"cid1Name": "厨具",
"cid2Name": "茶具",
"cid3Name": "咖啡具",
"detailAppUrl": "https://item.m.jd.com/product/47743493678.html",
"detailUrl": "https://item.jd.com/47743493678.html",
"dis": 0.531874537,
"imageUrl": "https://img13.360buyimg.com/img/jfs/t30616/107/1245450995/85283/c94a8d49/5cdb6eedN2eeed6e3.jpg",
"allImageUrls": [
"https://img13.360buyimg.com/img/jfs/t30616/107/1245450995/85283/c94a8d49/5cdb6eedN2eeed6e3.jpg",
"https://img13.360buyimg.com/img/jfs/t1/43462/38/4702/157488/5cdb6eedE475fc033/96f637b72d496338.jpg",
"https://img13.360buyimg.com/img/jfs/t11032/3/2927466590/142135/bbb2dc8f/5cdb6eedN6de0f5fe.jpg",
"https://img13.360buyimg.com/img/jfs/t11110/4/2902608409/294037/5798d58b/5cdb6eeeN7a7437c7.jpg",
],
"similarity": 0.9995388171331119,
"skuId": 47743493678,
"skuName": "【2019新品】咖啡机商用奶茶一体机全自动冷热多功能奶茶速溶果汁饮料机 扫码机器定制定金",
"skuPrice": "1066.00",
"wareLabel": "非自营"
},
...
{
"cls": 300,
"clsName": "全部",
"cid1Name": "厨具",
"cid2Name": "茶具",
"cid3Name": "咖啡具",
"detailAppUrl": "https://item.m.jd.com/product/34885974160.html",
"detailUrl": "https://item.jd.com/34885974160.html",
"dis": 0.942310035,
"imageUrl": "https://img1.360buyimg.com/img/jfs/t1/6616/13/965/58073/5bcae419E5e748d04/9f162f886db00201.jpg",
"allImageUrls": [
"https://img13.360buyimg.com/img/jfs/t1/6616/13/965/58073/5bcae419E5e748d04/9f162f886db00201.jpg",
"https://img13.360buyimg.com/img/jfs/
t1/6021/26/929/192706/5bcae419Eae7d9f3d/c198359aa0b518bc.jpg",
],
"similarity": 0.9727983623880836,
"skuId": 34885974160,
"skuName": "商用全自动速溶咖啡机自助饮料机冷热速溶咖啡奶茶一体机热饮机 X-98T-CF/3台式3热饮+热水+冰水",
"skuPrice": "3390.00",
"wareLabel": "非自营"
}
]
}
],
"img_height": 800,
"img_width": 800,
"main_category_list": "300|5|6|10|14|9|4|3|1|0|8|2|7|13|11|12",
"main_category_names": "全部|数码家电|食品饮料|家居家装|其他|个护洗化|箱包|鞋靴|上衣|裙装|配饰|下衣|玩具乐器|绿植|手机|图书影音",
"message": "Interface Succeed!",
"query_id": "3321c162ce8af41cb4376bdb2a514a46",
"status": "0"
}
}
四、错误码
1.系统级错误码
2.业务错误码
业务错误码(status) | message | 说明 |
---|---|---|
1002 | "Error Input!" | 读取图像失败 |
1005 | "Input size is bigger than 3.75M, Error Quit!" | 图像过大 |
20001 | "Request Service Error!" | 图像请求过程失败 |
20002 | "Request Service Error!" | 图像请求过程失败 |
20003 | "Request Service Error!" | 图像请求过程失败 |
20004 | "Request Service Error!" | 图像请求过程失败 |
20005 | "Request Service Error!" | 图像请求过程失败 |
20007 | "CHANNELID IS NECESSORY!" | channel_id(用户识别码)不能为空 |
20008 | "Channel_Id is not registered,please contact the administrator!" | 未注册用户识别码,不予以提供服务 |
20011 | "API is updating now. Your channel_id has been processed up to upper limit and can no longer be used today, please retry it tommorrow." | channel_id当日调用量超限 |
20012 | "'main_category_list=' is Necessory !" | 参数main_category_list缺失 |
20014 | "'action_type=' must Be 0 or 1 !" | 参数action_type值错误 |
20015 | "'main_body_rectangle=' is Necessory !" | 参数main_body_rectangle缺失 |
20016 | "'main_category_id=' is Necessory !" | 参数main_category_id缺失 |
20017 | "'channel_id=test' Does not Support USER ACTION!" | 测试接口不支持用户反馈请求 |
20018 | "categoryId error or categoryList is not the response one!" | 类目请求类别错误或者请求的类目列表错误 |
30001 | "Unknown Error!" | 未知错误 |
五、调用实例
postman实例
注意Content-Type设置为text/plain
1.首次请求
1)单主体
channel_id=xxx(以实际上线ID为准)&&imgBase64=/9j...(页面原因,不予以全部展示)
2)多主体
multi_bboxes=true&&channel_id=xxx(以实际上线ID为准)&&imgBase64=/9j...(页面原因,不予以全部展示)
3)直接使用传入图像进行商品召回
skip_detect=true&&channel_id=xxx(以实际上线ID为准)&&imgBase64=/9j...(页面原因,不予以全部展示)
4)返回相似商品个数限制
topK=5&&channel_id=xxx(以实际上线ID为准)&&imgBase64=/9j...(页面原因,不予以全部展示)
注意:首次请求、用户触发请求均支持
2.用户触发请求
1)切换搜索商品类目
action_type=0&&main_category_list=3|14|5|2|4|0|1&&main_category_id=0&&channel_id=xxx(以实际上线ID为准)&&imgBase64=/9j...(页面原因,不予以全部展示)
2)更改框选区域
action_type=1&&main_body_rectangle=20,20|400,400&&channel_id=xxx(以实际上线ID为准)&&imgBase64=/9j...(页面原因,不予以全部展示)
3)更改框选区域的情况下切换商品类目
action_type=0&&main_category_list=0|1|14|2|5|3|4&&main_category_id=3&&main_body_rectangle=20,20|400,400&&channel_id=xxx(以实际上线ID为准)&&imgBase64=/9j...(页面原因,不予以全部展示)
注意:接口不保留任何信息,如果需要交互,请求端需保留部分信息,比如多主体切换情况下,需保留之前返回的多主体位置信息