一、接口概述
淘系图搜API（即淘宝/天猫以图搜货接口）允许开发者通过上传商品图片，获取淘宝平台上的相似商品列表。其核心技术基于阿里巴巴的深度学习模型，支持服饰、家居、3C等多品类识别，广泛应用于比价、找同款、商品推荐等场景。
二、接入准备
1. 获取密钥
- AppKey：应用唯一标识（如
12345678）。 - AppSecret：签名加密密钥（如
a1b2c3d4e5f6）。 - AccessToken：通过OAuth 2.0授权获取（有效期24小时）。
三、接口调用实战
1. 请求示例（Python）
-- 请求示例 url 默认请求参数已经URL编码处理
curl -i "https://api-gw.onebound.cn/taobao/item_search_img/?key=<您自己的apiKey>&secret=<您自己的apiSecret>&imgid=http://g-search3.alicdn.com/img/bao/uploaded/i4/O1CN01IDpcD81zHbpHs1YgT_!!2200811456689.jpg"2. 关键参数说明
| 参数 | 必填 | 说明 |
|---|---|---|
| method | 是 | 固定值taobao.item.img.search |
| pic_url | 是 | 图片URL（需先上传至阿里云OSS，或使用multipart/form-data直接传文件） |
| cat_id | 否 | 类目ID（缩小搜索范围，如50010788表示女装） |
| sort | 否 | 排序方式（price_asc价格升序、volume_desc销量降序） |
四、返回数据结构解析
1. 成功响应示例
{
"items": {
"pagecount": 3,
"total_results": 60,
"real_total_results": 60,
"item": [
{
"title": "李宁篮球袜男款专业实战短筒运动袜子女夏跑步中长精英美式毛巾底",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01i8iOpV1rZSiOwyUYE_!!2068455645.jpg",
"promotion_price": "25.00",
"price": "25.00",
"num_iid": "785697155584",
"is_tmall": "false",
"area": "淄博",
"detail_url": "//item.taobao.com/item.htm?id=785697155584"
},
{
"title": "likeid篮球袜美式中长筒袜男夏季专业实战精英袜训练防滑运动袜子",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01tzf4lC1RMTNN4FCVw_!!623082097.jpg",
"promotion_price": "19.90",
"price": "19.90",
"num_iid": "706255675043",
"is_tmall": "false",
"area": "佛山",
"detail_url": "//item.taobao.com/item.htm?id=706255675043"
},
{
"title": "黑人月精英专业篮球袜加厚毛巾底中筒高筒运动袜子男",
"pic_url": "https://img.alicdn.com/imgextra/TB2luFSbTIlyKJjSZFMXXXvVXXa_!!546743164.jpg",
"promotion_price": "12.90",
"price": "12.90",
"num_iid": "543839578944",
"is_tmall": "false",
"area": "深圳",
"detail_url": "//item.taobao.com/item.htm?id=543839578944"
},
{
"title": "李宁运动袜子男短筒专业跑步篮球羽毛球女款棉透气防臭毛巾底秋冬",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01i8iOpV1rZSiOwyUYE_!!2068455645.jpg",
"promotion_price": "29.00",
"price": "29.00",
"num_iid": "751100232040",
"is_tmall": "false",
"area": "淄博",
"detail_url": "//item.taobao.com/item.htm?id=751100232040"
},
{
"title": "实战篮球袜精英款训练斯坦斯stance篮球袜子高筒559中筒359毛巾底",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01GJGJlc1fwZNLhfdEe_!!2215130674071.jpg",
"promotion_price": "43.90",
"price": "43.90",
"num_iid": "835954755321",
"is_tmall": "false",
"area": "石家庄",
"detail_url": "//item.taobao.com/item.htm?id=835954755321"
},
{
"title": "袜子男防臭防脚气夏季薄款运动抑菌中筒袜吸汗毛巾底篮球袜四季fm",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01Y89HYb2KdErlFuBmQ_!!4059759579.jpg",
"promotion_price": "20.71",
"price": "20.71",
"num_iid": "787279891547",
"is_tmall": "false",
"area": "金华",
"detail_url": "//item.taobao.com/item.htm?id=787279891547"
},
{
"title": "斗牛篮球精英袜男款高帮加厚毛巾底专业实战长筒防滑透气运动袜子",
"pic_url": "https://img.alicdn.com/imgextra/O1CN011VQ3pa1nRthROBUCP_!!2212944505087.jpg",
"promotion_price": "19.80",
"price": "19.80",
"num_iid": "751809323321",
"is_tmall": "true",
"area": "金华",
"detail_url": "//item.taobao.com/item.htm?id=751809323321"
},
{
"title": "包邮皇马主客场足球袜灰色白色紫色球袜毛巾底长筒过膝足球袜",
"pic_url": "https://img.alicdn.com/imgextra/TB2kc0RbwJlpuFjSspjXXcT.pXa_!!85536437.jpg",
"promotion_price": "16.00",
"price": "16.00",
"num_iid": "528042874974",
"is_tmall": "false",
"area": "郑州",
"detail_url": "//item.taobao.com/item.htm?id=528042874974"
},
{
"title": "科比欧文加厚专业篮球袜男中筒精英袜高帮毛巾底防滑透气吸汗防臭",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01YjiY1A1eHyLEsYqae_!!2908813847.png",
"promotion_price": "29.90",
"price": "29.90",
"num_iid": "636638770741",
"is_tmall": "true",
"area": "广州",
"detail_url": "//item.taobao.com/item.htm?id=636638770741"
},
{
"title": "情缘 袜子男士 足球袜 运动袜 提花袜 定制袜 长筒袜男定制",
"pic_url": "https://img.alicdn.com/imgextra/O1CN0130nTa524Rl8JXBJqz_!!0-item_pic.jpg",
"promotion_price": "12.80",
"price": "12.80",
"num_iid": "845255066462",
"is_tmall": "false",
"area": "鹤壁",
"detail_url": "//item.taobao.com/item.htm?id=845255066462"
},
{
"title": "儿童专用篮球袜男童女童专业秋冬加厚中筒纯棉袜实战训练运动袜子",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01wduMDu21IeIqyyIKI_!!6000000006962-0-yinhe.jpg",
"promotion_price": "13.90",
"price": "13.90",
"num_iid": "710555714441",
"is_tmall": "false",
"area": "佛山",
"detail_url": "//item.taobao.com/item.htm?id=710555714441"
},
{
"title": "春秋款透气中筒篮球袜纯棉男女儿童大码彩色黄绿蓝色运动训练",
"pic_url": "https://img.alicdn.com/imgextra/O1CN011FkxCc1gCb4jaQfos_!!3418834106.jpg",
"promotion_price": "26.80",
"price": "26.80",
"num_iid": "675462541686",
"is_tmall": "false",
"area": "重庆",
"detail_url": "//item.taobao.com/item.htm?id=675462541686"
},
{
"title": "3双岩也中筒长袜子男生运动篮球实战透气速干健身白色毛巾底潮ins",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01F2kqlI24WnU7roHZk_!!2912737399.jpg",
"promotion_price": "39.90",
"price": "39.90",
"num_iid": "839482989746",
"is_tmall": "false",
"area": "佛山",
"detail_url": "//item.taobao.com/item.htm?id=839482989746"
},
{
"title": "Uponey篮球袜男美式毛巾底透气精英中筒防滑训练长筒实战运动袜子",
"pic_url": "https://img.alicdn.com/imgextra/O1CN015m6htf1pYt3Jt5mkM_!!552855373.jpg",
"promotion_price": "29.00",
"price": "29.00",
"num_iid": "750145478658",
"is_tmall": "false",
"area": "青岛",
"detail_url": "//item.taobao.com/item.htm?id=750145478658"
},
{
"title": "HG篮球袜男高帮中筒毛巾底实战长筒精袜专业运动袜子闪袭系列",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01r1zqmE1pYskTiE3jM_!!552855373.jpg",
"promotion_price": "21.00",
"price": "21.00",
"num_iid": "653241419632",
"is_tmall": "false",
"area": "青岛",
"detail_url": "//item.taobao.com/item.htm?id=653241419632"
},
{
"title": "李宁运动袜子男士吸汗透气跑步篮球袜防嗅抗菌女短中筒精硫棉夏季",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01kkCB3k1erF6BlXQTK_!!3851683924.jpg",
"promotion_price": "29.00",
"price": "29.00",
"num_iid": "775037189585",
"is_tmall": "false",
"area": "南京",
"detail_url": "//item.taobao.com/item.htm?id=775037189585"
},
{
"title": "跨境篮球袜男款专业加厚毛巾底防滑吸汗中筒袜精英袜高帮运动袜子",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01ACnac92NPRpb7Fo48_!!0-item_pic.jpg",
"promotion_price": "52.32",
"price": "52.32",
"num_iid": "845586474670",
"is_tmall": "false",
"area": "石家庄",
"detail_url": "//item.taobao.com/item.htm?id=845586474670"
},
{
"title": "实战专业篮球毛巾加厚运动精英袜中筒男中筒防滑高帮训练透气长筒",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01GwZNBO229Ju9OFIRW_!!2341307077.jpg",
"promotion_price": "10.80",
"price": "10.80",
"num_iid": "783158595757",
"is_tmall": "false",
"area": "广州",
"detail_url": "//item.taobao.com/item.htm?id=783158595757"
},
{
"title": "袜子女春夏秋季女士毛巾底中筒袜吸湿透气纯棉运动篮球袜短袜女袜",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01RS0usy1KaUArb2hZI_!!1674221180.jpg",
"promotion_price": "2.88",
"price": "2.88",
"num_iid": "705555992925",
"is_tmall": "false",
"area": "石家庄",
"detail_url": "//item.taobao.com/item.htm?id=705555992925"
},
{
"title": "有志者UZIS实战训练篮球袜男专业防滑中长筒网眼透气运动袜斗牛士",
"pic_url": "https://img.alicdn.com/imgextra/O1CN01aqkEh524wu0B8wfWN_!!2207237977456.jpg",
"promotion_price": "23.00",
"price": "23.00",
"num_iid": "773859448281",
"is_tmall": "false",
"area": "长沙",
"detail_url": "//item.taobao.com/item.htm?id=773859448281"
}
],
"page_size": 20,
"page": 1,
"_ddf": "cdy"
},
"error_code": "0000",
"reason": "ok",
"secache": "805dd061d51a733c7a85711ba0a36267",
"secache_time": 1729492509,
"secache_date": "2024-10-21 14:35:09",
"translate_status": "",
"translate_time": 0,
"language": {
"default_lang": "cn",
"current_lang": "cn"
},
"error": "",
"cache": 0,
"api_info": "today:83 max:10000 all[3190=83+38+3069];expires:2030-10-30",
"execution_time": "2.298",
"server_time": "Beijing/2024-10-21 14:35:09",
"client_ip": "61.131.237.50",
"call_args": {
"imgid": "http://g-search3.alicdn.com/img/bao/uploaded/i4/O1CN01IDpcD81zHbpHs1YgT_!!2200811456689.jpg"
},
"api_type": "taobao",
"translate_language": "zh-CN",
"translate_engine": "",
"server_memory": "4.35MB",
"request_id": "gw-1.6715f61ad53ba",
"last_id": "3628194757"
}2. 核心字段处理
- 去重逻辑：根据
item_id合并同一商品的不同SKU。 - 价格清洗：将
price字段中的价格区间（如"159.00-299.00"）拆分为最低价和最高价。 - 图片优化：替换
image_url为CDN链接以加速加载。
五、常见问题与解决方案
| 状态代码(error_code) | 状态信息 | 详细描述 | 是否收费 |
|---|---|---|---|
| 0000 | success | 接口调用成功并返回相关数据 | 是 |
| 2000 | Search success but no result | 接口访问成功，但是搜索没有结果 | 是 |
| 4000 | Server internal error | 服务器内部错误 | 否 |
| 4001 | Network error | 网络错误 | 否 |
| 4002 | Target server error | 目标服务器错误 | 否 |
| 4003 | Param error | 用户输入参数错误 | 忽略 |
| 4004 | Account not found | 用户帐号不存在 | 忽略 |
| 4005 | Invalid authentication credentials | 授权失败 | 忽略 |
| 4006 | API stopped | 您的当前API已停用 | 忽略 |
| 4007 | Account stopped | 您的账户已停用 | 忽略 |
| 4008 | API rate limit exceeded | 并发已达上限 | 忽略 |
| 4009 | API maintenance | API维护中 | 忽略 |
| 4010 | API not found with these values | API不存在 | 忽略 |
| 4012 | Please add api first | 请先添加api | 忽略 |
| 4013 | Number of calls exceeded | 调用次数超限 | 忽略 |
| 4014 | Missing url param | 参数缺失 | 忽略 |
| 4015 | Wrong pageToken | 参数pageToken有误 | 忽略 |
| 4016 | Insufficient balance | 余额不足 | 忽略 |
| 4017 | timeout error | 请求超时 | 否 |
| 5000 | unknown error | 未知错误 |
、合规与风控
- 数据使用限制：不得存储用户隐私数据（如商品评论中的个人信息）。
- 反爬策略：避免规律性调用（随机化请求间隔，使用动态代理IP）。
- 资质合规：若涉及跨境业务，需申请《跨境电商数据出境安全评估》。
通过合理利用淘系图搜API，开发者可快速构建智能图像搜索应用。建议结合业务需求，在数据清洗、缓存策略、异步处理等环节持续优化，以提升用户体验和系统稳定性。
