一、接口概述
淘系圖搜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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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": "http://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，開發者可快速構建智能圖像搜索應用。建議結合業務需求，在數據清洗、緩存策略、異步處理等環節持續優化，以提升用戶體驗和系統穩定性。
