首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >淘宝拍立淘按图搜索 API 接口技术文档(完整JSON样例)

淘宝拍立淘按图搜索 API 接口技术文档(完整JSON样例)

原创
作者头像
Anzexi58
发布2026-06-07 15:12:15
发布2026-06-07 15:12:15
310
举报
文章被收录于专栏:API接口开发API接口开发

前言

一、接口概述

淘宝拍立淘按图搜索接口(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(完整真实样例)

以下为官方原生完整返回数据,包含相似度分数、天猫标识、价格、销量、商品链接、主图、店铺信息等全部核心字段。

代码语言:javascript
复制
{
    "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嵌套深、字段冗余,开发中统一清洗为扁平化标准结构,可直接入库、比价、做同款匹配:

代码语言:javascript
复制
{
    "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. 图片地址无效

代码语言:javascript
复制
{
    "error_response": {
        "code": 40026,
        "msg": "invalid img_url",
        "sub_msg": "图片链接无法访问或格式错误"
    }
}

2. 接口权限不足

代码语言:javascript
复制
{
    "error_response": {
        "code": 22,
        "msg": "Insufficient Permissions",
        "sub_msg": "未开通拍立淘搜索接口权限"
    }
}

3. 请求限流

代码语言:javascript
复制
{
    "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 结构标准、数据维度完整,包含价格、销量、店铺、相似度等关键商业数据。通过结构化清洗后,可直接支撑找货、比价、侵权检测、智能识图等企业级业务,是合规、稳定、高效的视觉电商数据解决方案。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 一、接口概述
  • 二、接口基础信息
  • 三、核心请求参数
  • 四、接口原始返回 JSON(完整真实样例)
  • 五、核心字段详细说明
  • 六、结构化清洗后标准 JSON(业务落地模型)
  • 七、错误返回 JSON 样例(开发排错必备)
    • 1. 图片地址无效
    • 2. 接口权限不足
    • 3. 请求限流
  • 八、核心开发实战要点
  • 九、业务应用场景
  • 十、总结
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档