一、接口概述
淘宝按图搜索商品API（taobao.item.img.search）允许开发者通过上传图片，在淘宝海量商品库中检索视觉相似的商品。该接口采用基于内容的图像检索技术（CBIR），主要匹配维度包括：
主体轮廓相似度
颜色分布特征
纹理模式匹配
局部关键点对比
数学表达为相似度计算函数： $$S(I_q, I_t) = \alpha \cdot C_{color} + \beta \cdot C_{texture} + \gamma \cdot C_{shape}$$ 其中$I_q$为查询图像，$I_t$为商品图像，$\alpha+\beta+\gamma=1$为权重系数。
二、技术实现要点
格式限制：JPG/PNG（建议300×300以上分辨率）
文件大小：≤500KB
背景建议：纯色背景提升识别准确率
import requests
import hashlib
import time
def taobao_img_search(image_path):
# 基础参数配置
app_key = "YOUR_APP_KEY"
app_secret = "YOUR_APP_SECRET"
api_url = "https://api.taobao.com/router/rest"
# 构建请求参数
params = {
"method": "taobao.item.img.search",
"app_key": app_key,
"timestamp": str(int(time.time() * 1000)),
"format": "json",
"v": "2.0",
"sign_method": "md5",
"image": open(image_path, 'rb')
}
# 生成签名
param_str = ''.join(f"{k}{v}" for k,v in sorted(params.items()))
sign = hashlib.md5((app_secret + param_str + app_secret).encode()).hexdigest()
params["sign"] = sign
# 发送请求
response = requests.post(api_url, files=params)
return response.json()
三、返回数据结构解析
{
"item_search_img_response": {
"items": {
"item": [
{
"item_id": "643290283744",
"title": "2023新款女装连衣裙",
"pic_url": "https://img.alicdn.com/xxx.jpg",
"price": "159.00",
"similarity": "0.87" // 相似度得分
}
],
"total_results": 128
},
"request_id": "q6x3vcy5t84d"
}
}
四、最佳实践建议
裁剪无关背景区域
使用OpenCV进行边缘增强：
import cv2
img = cv2.imread("input.jpg")
edges = cv2.Canny(img, 100, 200)
cv2.imwrite("enhanced.jpg", edges)
筛选高相似度商品
filtered_items = [item for item in result['items'] if float(item['similarity']) > 0.8]
按价格排序
sorted_items = sorted(filtered_items, key=lambda x: float(x['price']))
五、常见错误代码
错误码 含义 解决方案
7 图片格式不支持 转换JPG/PNG格式
15 图片尺寸过大 压缩至500KB以内
32 每日调用量超限 申请提升配额
40 签名验证失败 检查签名生成逻辑
六、高级应用场景
上传多张图片进行联合搜索
params = {
"image": open("main.jpg", 'rb'),
"aux_images": [
open("detail1.jpg", 'rb'),
open("detail2.jpg", 'rb')
]
}
注：实际开发需遵守《淘宝开放平台API使用协议》，每日调用限额需根据应用等级申请。建议使用官方SDK（top-sdk-java/top-sdk-python）简化签名流程。
