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

原创

Anzexi58

发布于 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（完整真实样例）

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

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

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

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

api-key

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

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

api-key

登录后参与评论

0 条评论

热度