一、接口基础概述

1.1 接口定位

项目核心使用淘宝拍立淘搜索查询接口，（如添加 Taobaoapi2014），无需店铺卖家权限，直接调用封装 API，一键获取已封装好的数据 API 采集，适合批量查询、中小卖家使用，适配竞品分析与市场调研场景。

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

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

1.2 基础调用规范

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

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

代码语言：javascript

{
    "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 分页统计顶层字段

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

4.2 单品 item 核心业务字段

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

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

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

json

代码语言：javascript

{
    "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"
        }
    ]
}

模型业务优化说明

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