前言
在电商业务中，以图搜同款 / 相似款是非常高频的能力：货源溯源、ERP 铺货、竞品比价、选品工具、内容平台商品挂载，都需要输入一张图片 URL，拿回天猫、淘宝平台结构化商品列表。天猫图片搜索底层就是拍立淘视觉检索能力，接口taobao.item_search_img，支持传入公网图片地址，返回天猫标品 + 淘宝商品混合结果，可通过is_tmall字段过滤只保留天猫商品。
一、接口基础说明
接口名称：taobao.item_search_img（拍立淘按图搜商品）
请求网关：TOP 开放平台网关 https://gw.api.taobao.com/router/rest
请求方式：GET / POST
返回格式：JSON
输入方式二选一：
img_url：公网可直接访问的图片地址（业务最常用）
image：图片 Base64 编码字符串
图片约束：JPG/PNG，文件≤2MB，图片内商品主体占比≥60%，匹配效果最佳
输出：同款、高度相似商品，包含标题、价格、销量、商品 ID、详情链接、是否天猫商品、相似度得分等字段
业务落地场景
货源溯源：拿到下游客户提供产品图，输入图片 URL，快速定位天猫源头店铺与同款货源
ERP / 铺货系统：外部素材图，直接检索平台已有商品，减少手动录入
竞品监控：竞品主图链接批量图搜，找出全平台同款比价
采购选品：B 端采购拿到样品图片，检索天猫在售规格、价格区间
内容导购：图文内容，通过图片匹配对应商品挂载链接
业务小案例：某采购对接产品部，拿到供应商产品图片链接，调用该接口，过滤is_tmall=true，短时间拿到天猫渠道同款的售价、销量、店铺，快速完成竞品调研，不用人工逐个搜索。
二、核心请求参数
表格
三、关键返回字段解析
json
{
"items": {
"item": [
{
"title": "商品标题",
"num_iid": "商品ID",
"pic_url": "商品主图",
"price": "售卖价",
"orginal_price": "原价",
"sales": "销量",
"nick": "店铺名称",
"detail_url": "商品详情链接",
"is_tmall": true,
"similarity_score": 0.94
}
]
}
}
重点：is_tmall布尔字段，true 代表天猫商品，false 为淘宝 C 店，业务只需要天猫结果时直接过滤该字段即可。
similarity_score相似度分数，0‑1 区间，数值越高图片匹配度越高，业务上建议过滤≥0.7 的结果。
四、Python 极简调用示例
python
运行
import requests
import time
import hashlib
def get_tmall_similar_by_img_url(app_key, app_secret, img_url):
params = {
"method": "taobao.item_search_img",
"app_key": app_key,
"timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
"format": "json",
"v": "2.0",
"img_url": img_url,
"page_no":1,
"page_size":20
}
# TOP签名生成逻辑
sorted_items = sorted(params.items(), key=lambda x:x[0])
raw = "".join([k+str(v) for k,v in sorted_items])
sign_str = app_secret + raw + app_secret
params["sign"] = hashlib.md5(sign_str.encode("utf8")).hexdigest().upper()
resp = requests.get("https://gw.api.taobao.com/router/rest", params=params)
return resp.json()
if name == "main":
# 传入公网图片地址
res = get_tmall_similar_by_img_url("your_key","your_secret","https://xxx/demo.jpg")
print(res)
五、开发踩坑避坑指南
img_url 必须公网可访问：内网、本地路径、带防盗链的图片链接会检索失败，图片服务器不能校验 referer。外部图片无法直接访问时，需要先上传到可公网访问的资源服务，拿到新 url 再调用接口CSDN博...。
权限门槛：原生 TOP 开放平台该接口不是默认开通，需要单独申请图像检索权限，个人开发者很难直接拿到完整权限，企业业务可以选择成熟服务封装降低接入成本。
返回结果是淘宝 + 天猫混合池，不要默认全部是天猫，必须判断is_tmall做过滤。
图片质量影响结果：背景杂乱、商品占比小、多物体共存，会出现匹配跑偏；业务系统可前置做图片裁剪，抠出主体部分再调用。
限流与并发：官方接口有 QPS 限制，批量任务做好队列限流，避免 429 报错。
签名不要写错：参数排序、拼接、首尾拼接 app_secret，是调用报错最高频原因。
六、延伸业务链路
拿到图搜返回商品 ID 后，可以联动商品详情接口，获取 SKU、库存、规格；评论接口获取用户评价；历史价格接口做价格趋势分析，完整构建商品画像，服务采购、选品、竞品分析业务。
