淘宝拍立淘按图搜索 API 接口技术文档（完整JSON样例）
前言
一、接口概述
淘宝拍立淘按图搜索接口（item_search_img），是淘宝开放平台核心图像检索接口。通过上传图片URL/图片二进制，可实现以图搜同款、以图搜相似款，返回全网相似商品、匹配度、价格、销量、店铺、主图、商品链接等数据。
常用于：同款比价、货源找货、图片识别商品、侵权排查、铺货匹配、同款竞品分析、图像检索系统开发。
二、接口基础信息
接口名称：item_search_img（拍立淘按图搜索）
请求地址：o0b.cn/anzexi
请求方式：GET / POST
数据格式：JSON
核心能力：图片检索、相似度匹配、同款/相似商品批量返回
分页能力：支持 page_no / page_size 分页，最大每页100条
三、核心请求参数
参数名 | 是否必填 | 说明 |
|---|---|---|
img_url | 是 | 待检索图片网络地址（必须可公网访问） |
page_no | 否 | 页码，默认1 |
page_size | 否 | 每页数量，最大100 |
similar | 否 | 1=优先同款，0=优先相似款 |
四、接口原始返回 JSON（完整真实样例）
以下为官方原生完整返回数据，包含相似度分数、天猫标识、价格、销量、商品链接、主图、店铺信息等全部核心字段。
{
"item_search_img_response": {
"request_id": "2026060715023600123",
"total_results": 68,
"items": {
"item": [
{
"num_iid": "68952314567890123",
"title": "2026夏季新款纯棉短袖T恤女宽松百搭纯色简约上衣",
"price": "59.90",
"promotion_price": "39.90",
"pic_url": "https://img1.taobao.com/xxx_main.jpg",
"detail_url": "https://item.taobao.com/item.htm?id=68952314567890123",
"sales": 12680,
"location": "广东 广州",
"nick": "XX女装旗舰店",
"is_tmall": true,
"match_rate": 0.96,
"category": "女装/女士精品>T恤"
},
{
"num_iid": "68123456789012345",
"title": "韩系简约纯棉短袖女夏季宽松百搭基础款纯色T恤上衣",
"price": "69.00",
"promotion_price": "45.00",
"pic_url": "https://img2.taobao.com/xxx_2.jpg",
"detail_url": "https://item.taobao.com/item.htm?id=68123456789012345",
"sales": 8960,
"location": "浙江 杭州",
"nick": "XX韩风服饰店",
"is_tmall": false,
"match_rate": 0.89,
"category": "女装/女士精品>T恤"
}
]
}
}
}五、核心字段详细说明
total_results：本次图片检索匹配到的商品总数num_iid：商品唯一ID（核心主键）title：商品标题price：商品原价promotion_price：实时促销价（成交价）pic_url：商品主图地址detail_url：商品详情真实链接sales：商品累计销量location：发货地nick：店铺名称is_tmall：是否天猫店铺（正品权重更高）match_rate：图片相似度0~1，越高越匹配category：商品所属类目
六、结构化清洗后标准 JSON（业务落地模型）
原生JSON嵌套深、字段冗余，开发中统一清洗为扁平化标准结构，可直接入库、比价、做同款匹配：
{
"request_id": "2026060715023600123",
"total": 68,
"item_list": [
{
"num_iid": "68952314567890123",
"title": "2026夏季新款纯棉短袖T恤女宽松百搭纯色简约上衣",
"origin_price": "59.90",
"sale_price": "39.90",
"main_image": "https://img1.taobao.com/xxx_main.jpg",
"item_url": "https://item.taobao.com/item.htm?id=68952314567890123",
"sales": 12680,
"location": "广东 广州",
"shop_name": "XX女装旗舰店",
"is_tmall": true,
"similarity": 0.96,
"category": "女装/女士精品>T恤",
"match_level": "高度同款"
},
{
"num_iid": "68123456789012345",
"title": "韩系简约纯棉短袖女夏季宽松百搭基础款纯色T恤上衣",
"origin_price": "69.00",
"sale_price": "45.00",
"main_image": "https://img2.taobao.com/xxx_2.jpg",
"item_url": "https://item.taobao.com/item.htm?id=68123456789012345",
"sales": 8960,
"location": "浙江 杭州",
"shop_name": "XX韩风服饰店",
"is_tmall": false,
"similarity": 0.89,
"category": "女装/女士精品>T恤",
"match_level": "相似款"
}
]
}七、错误返回 JSON 样例（开发排错必备）
1. 图片地址无效
{
"error_response": {
"code": 40026,
"msg": "invalid img_url",
"sub_msg": "图片链接无法访问或格式错误"
}
}2. 接口权限不足
{
"error_response": {
"code": 22,
"msg": "Insufficient Permissions",
"sub_msg": "未开通拍立淘搜索接口权限"
}
}3. 请求限流
{
"error_response": {
"code": 429,
"msg": "Request Too Frequently",
"sub_msg": "接口调用频率超限，请稍后重试"
}
}八、核心开发实战要点
相似度筛选：
match_rate ≥ 0.9判定为同款商品，用于精准找货图片要求：必须公网可访问 HTTPS 图片，本地图片需先上传获取URL
去重规则：以
num_iid作为商品唯一主键排序策略：优先按相似度、销量、价格综合排序
分页限制：最大100页，批量采集需做分页闭环
九、业务应用场景
以图搜同款、货源精准匹配、无货源铺货
同款商品比价、全网最低价监控
商品图片侵权检测、相似商品排查
服装、箱包、饰品、3C 类视觉类商品选品
智能识图系统、小程序以图搜商品功能开发
十、总结
淘宝拍立淘按图搜索 API（item_search_img）是电商图像检索领域核心接口，依靠图片相似度算法实现精准同款匹配。原生 JSON 结构标准、数据维度完整，包含价格、销量、店铺、相似度等关键商业数据。通过结构化清洗后，可直接支撑找货、比价、侵权检测、智能识图等企业级业务，是合规、稳定、高效的视觉电商数据解决方案。
