淘宝拍立淘图片搜索 API 技术说明文档（taobao.item.search_img｜含原始 JSON + 落地结构化模型）

原创

wx19970108018

发布于 2026-06-16 14:08:52

550

文章被收录于专栏：经验经验

一、接口基础概述

1.1 接口定位

taobao.item.search_img 即拍立淘官方图搜接口，依托图像特征检索算法，传入图片即可批量匹配淘宝、天猫同款 / 相似商品，是跨境选品、竞品溯源、爆款挖掘、同款比价项目的核心视觉数据源。

相比网页爬虫，官方接口返回标准化结构化数据，不受页面改版影响，合规稳定，支持分页批量拉取匹配商品，自带图片相似度打分，可直接用于同款筛选逻辑。

1.2 基础调用规范

接口标识：taobao.item.search_img
请求方式：HTTPS POST（推荐，避免大图 Base64 参数超长截断）
响应格式：JSON
接口版本：2.0
请求网关： c0b.cc/R4rbK2 （HTTPS，支持 GET/POST）
准入要求：企业实名开发者，单独申请图片检索权限，审核通过后方可调用

1.3 调用风控限制

QPS 上限：普通商用额度 5 次 / 秒，批量采集需做限流队列削峰
日调用额度：分档位套餐，超限触发临时限流封禁 5~10 分钟，长期高频压测会回收接口权限
图片传入二选一规则：公网可访问图片 URL / Base64 编码字符串
图片标准：JPG/PNG，文件≤2MB，商品主体占画面≥60%，无水印遮挡可大幅提升匹配准确率

二、请求核心入参

2.1 公共通用参数（全部参与签名计算，必填）

表格

参数名	类型	说明
method	String	固定值 taobao.item.search_img
app_key	String	应用唯一身份标识
timestamp	String	标准时间戳 yyyy-MM-dd HH:mm:ss，服务器时差不可超过 5 分钟
v	String	固定 2.0
format	String	json
sign	String	MD5 加密签名
access_token	String	OAuth 授权令牌

2.2 业务检索参数

表格

参数名	必填	类型	说明
image_url	二选一	String	公网图片直链，优先推荐使用
image	二选一	String	图片 Base64 编码，需清除换行、空格冗余字符
cid	否	Long	类目 ID，限定类目可过滤跨类目无关商品，提升匹配精度
page_no	否	Int	分页页码，默认 1
page_size	否	Int	单页返回条数，区间 1~100，默认 20
sort	否	String	排序规则：price_asc/price_desc/sales（销量）

三、原始完整返回 JSON 示例

json

{
    "taobao_item_search_img_response": {
        "request_id": "2026061613421500896",
        "total_results": 62,
        "real_total_results": 62,
        "pagecount": 4,
        "page_no": 1,
        "page_size": 20,
        "items": {
            "item": [
                {
                    "num_iid": "714589632145",
                    "title": "2026夏季纯棉短袖女宽松纯色百搭基础T恤",
                    "pic_url": "https://img.alicdn.com/xxx.jpg",
                    "promotion_price": "39.90",
                    "price": "79.00",
                    "sales": 12560,
                    "post_fee": "0.00",
                    "detail_url": "https://item.taobao.com/item.htm?id=714589632145",
                    "seller_nick": "潮流女装旗舰店",
                    "area": "浙江杭州",
                    "is_tmall": true,
                    "match_rate": 0.92,
                    "category": "女装/女士精品>T恤"
                },
                {
                    "num_iid": "723698541256",
                    "title": "简约白色纯棉短袖男女同款休闲上衣",
                    "pic_url": "https://img.alicdn.com/xxx2.jpg",
                    "promotion_price": "35.80",
                    "price": "69.00",
                    "sales": 8930,
                    "post_fee": "5.00",
                    "detail_url": "https://item.taobao.com/item.htm?id=723698541256",
                    "seller_nick": "平价服饰优选店",
                    "area": "广东广州",
                    "is_tmall": false,
                    "match_rate": 0.85,
                    "category": "女装/女士精品>T恤"
                }
            ]
        }
    }
}

四、原始 JSON 字段释义

4.1 分页统计顶层字段

request_id：单次请求唯一流水号，用于日志排查、链路追踪
total_results：当前检索匹配商品总数
real_total_results：平台真实商品总量，分页上限以此为准
pagecount：总分页数
page_no/page_size：当前页码、单页返回数量

4.2 单品 item 核心业务字段

num_iid：商品唯一主键，对接商品详情 API 的核心标识
title：商品完整标题，用于关键词筛选、文案分析
pic_url：商品主图 CDN 地址
price：商品原价（划线价）
promotion_price：实时活动售价，比价、利润测算核心字段
sales：累计销量，爆款权重打分依据
post_fee：运费，核算整体拿货成本
detail_url：商品详情原生链接
seller_nick：店铺名称
area：发货地区
is_tmall：布尔值，区分天猫旗舰店 / 淘宝 C 店，货源权重筛选
match_rate：图片相似度 0~1，数值越高代表同款匹配度越高，业务一般过滤 0.7 以下低匹配商品
category：商品多级类目名称

五、落地标准化结构化模型（业务清洗后入库实体）

原生 JSON 嵌套层级深、冗余字段多，项目统一扁平化清洗，直接适配 MySQL/Redis 存储、爆款打分系统，模型如下：

json

{
    "requestId": "2026061613421500896",
    "queryImgUrl": "检索原图地址",
    "totalMatch": 62,
    "pageNum": 1,
    "pageSize": 20,
    "itemList": [
        {
            "itemId": "714589632145",
            "itemTitle": "2026夏季纯棉短袖女宽松纯色百搭基础T恤",
            "mainImg": "https://img.alicdn.com/xxx.jpg",
            "originalPrice": "79.00",
            "salePrice": "39.90",
            "monthSales": 12560,
            "shippingFee": "0.00",
            "itemLink": "https://item.taobao.com/item.htm?id=714589632145",
            "shopName": "潮流女装旗舰店",
            "shipArea": "浙江杭州",
            "isTmall": true,
            "similarScore": 0.92,
            "categoryName": "女装/女士精品>T恤",
            "matchLevel": "high",
            "createTime": "2026-06-16 13:42:15"
        }
    ]
}

模型业务优化说明

新增similarScore/matchLevel：根据相似度自动分级 high (≥0.8)/mid (0.7~0.8)/low (<0.7)，业务快速过滤低匹配杂款
统一字段命名驼峰化，适配 Java/Go 后端实体类映射
保留原始请求图片、采集时间戳，用于数据溯源、缓存过期判定
剔除平台冗余底层字段，仅保留选品、比价、溯源所需核心维度，减少数据库存储开销

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

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

开发经验