阿里巴巴中国站按图搜索1688商品（拍立淘）API 返回值说明

一、接口概述

item_search_img 是1688开放平台提供的图像搜索接口，俗称"拍立淘"。该接口允许开发者通过上传商品图片，在1688平台快速匹配相似或同款商品，广泛应用于电商比价、商品溯源、智能选品等场景。

表格

复制

接口名称	功能	图片上传方式	返回格式
item_search_img	以图搜1688商品	①图片URL ②Base64编码	JSON

二、返回值顶层结构

API返回标准JSON格式，顶层结构如下：

复制代码

{
  "code": 200,
  "msg": "success",
  "request_id": "12345abcde",
  "items": {
    "page": "1",
    "real_total_results": 670,
    "total_results": 670,
    "pagecount": 14,
    "page_size": "50",
    "item": [ ... ]
  }
}

字段说明

字段	类型	说明
`code`	Integer	状态码，`200`表示成功，`401`未授权，`429`请求频率过高
`msg`	String	状态描述，如`"success"`或错误信息
`request_id`	String	请求唯一标识符，用于问题追踪和调试
`items`	Object	搜索结果容器对象

三、分页信息字段（items层级）

字段	类型	示例	业务含义
`page`	String	`"1"`	当前页码
`real_total_results`	Integer	`670`	实际库中命中同款+相似款总量
`total_results`	Integer	`670`	本次可翻页总量（≤real_total_results）
`pagecount`	Integer	`14`	总页数
`page_size`	String	`"50"`	每页条数（默认50，最大100）
`item`	Array	`[...]`	商品列表数组

四、商品详情字段（item数组内）

每条商品记录包含以下核心字段：

4.1 基础信息

字段	类型	示例	业务含义
`num_iid`	String	`"728510689123"`	商品数字ID，可用于`item_get`接口获取详情
`title`	String	`"2025夏新款真丝连衣裙"`	商品标题
`pic_url`	String	`https://cbu01.alicdn.com/...`	商品主图URL（通常为400×400压缩图）
`detail_url`	String	`https://detail.1688.com/offer/728510689123.html`	PC端详情页链接

4.2 价格信息

价格字段存在两种返回格式，需做类型判断处理：

单SKU简化版（最常见）：

复制代码

{
  "price": "99.00",
  "unit": "件"
}

多SKU完整版：

复制代码

{
  "price": {
    "min_price": 85.00,
    "max_price": 135.00,
    "unit": "件"
  },
  "price_range": {
    "min_price": 85,
    "max_price": 135
  }
}

字段	类型	说明
`price`	String/Float/Object	标价，单SKU时直接返回数值，多SKU时返回对象
`price_range`	Object	多SKU时的价格区间
`original_price`	String	商品原价（如有促销）
`promotion_price`	String	促销价（如有活动）
`unit`	String	计价单位，如`"件"`、`"套"`

4.3 交易信息

表格

复制

字段	类型	示例	业务含义
`sales` / `sales_count`	Integer	`327`	近30天已售件数
`moq`	Integer	`2`	Minimum Order Quantity，起订量（2件起批）
`transaction`	Object	`{...}`	部分版本包含30天成交额`turnover`

4.4 供应商信息

字段	类型	示例	业务含义
`supplier_name`	String	`"杭州xx服饰有限公司"`	店铺/供应商名称
`supplier_id` / `seller_id`	String	`"b2b-123456"`	店铺ID，可接`seller_info`接口
`seller_nick`	String	`"某某旗舰店"`	卖家昵称
`location` / `area`	String	`"浙江杭州市"`	发货地/卖家所在地

4.5 匹配与分类信息

字段	类型	示例	业务含义
`similarity` / `similarity_score`	Float	`0.87`	图片相似度（0-1之间），>0.8可视为同款
`search_type`	Integer	`1`	1=同款，2=相似款（由请求参数决定）
`cat_id`	String	`"1031912"`	商品类目ID，可用于类目分布分析

五、完整响应示例

java 复制代码

{
  "code": 200,
  "msg": "success",
  "request_id": "2025021414300012345",
  "items": {
    "page": "1",
    "real_total_results": 156,
    "total_results": 156,
    "pagecount": 4,
    "page_size": "40",
    "item": [
      {
        "num_iid": "728510689123",
        "title": "2025夏季新款真丝印花连衣裙",
        "pic_url": "https://cbu01.alicdn.com/img/ibank/O1CN01xxxxx.jpg_400x400.jpg",
        "price": "128.00",
        "price_range": {
          "min_price": 95,
          "max_price": 135
        },
        "unit": "件",
        "moq": 2,
        "sales": 1050,
        "similarity": 0.92,
        "detail_url": "https://detail.1688.com/offer/728510689123.html",
        "supplier_name": "杭州丝绸源头厂家",
        "supplier_id": "b2b-888888",
        "location": "浙江 杭州市",
        "cat_id": "1031912",
        "search_type": 1
      },
      {
        "num_iid": "728510689124",
        "title": "真丝连衣裙女夏季新款",
        "pic_url": "https://cbu01.alicdn.com/img/ibank/O1CN01yyyyy.jpg_400x400.jpg",
        "price": {
          "min_price": 88.00,
          "max_price": 158.00
        },
        "unit": "件",
        "moq": 3,
        "sales_count": 567,
        "similarity_score": 0.85,
        "detail_url": "https://detail.1688.com/offer/728510689124.html",
        "seller_nick": "苏州丝绸批发店",
        "area": "江苏 苏州市",
        "cat_id": "1031912"
      }
    ]
  }
}

六、相似度（Similarity）使用指南

相似度是拍立淘的核心指标，建议按以下区间处理：

相似度区间	业务含义	应用建议
≥ 0.90	极高概率同款	可直接做比价表，视为同一商品
0.80-0.89	款式接近	布料/印花略有差异，需人工确认
0.60-0.79	相似元素	仅领型、图案等局部相似
< 0.60	基本无关	建议前端过滤，减少噪音

七、错误响应格式

当请求失败时，返回结构如下：

复制代码

{
  "code": 401,
  "msg": "Unauthorized",
  "request_id": "2025021414300099999",
  "error": {
    "code": 401,
    "message": "Unauthorized: Invalid API Key"
  }
}

常见错误码：

错误码	含义	处理建议
`401`	未授权	检查API Key和权限
`429`	请求频率过高	降低QPS，申请更高配额
`400`	参数错误	检查imgid格式或图片大小
`500`	服务器内部错误	联系平台技术支持

八、关键字段应用建议

moq（起订量）：做Dropshipping或小额批发时务必检查，避免无法下单
cat_id（类目ID）：抓取后可做类目分布分析，优化选品策略
supplier_id：同一供应商往往有多个商品链接，可用于合并去重
pic_url处理 ：返回的是400×400压缩图，如需原图将.search.jpg替换为.jpg

九、Python调用示例

python 复制代码

import requests
import time
import os

# 配置参数
APP_KEY = os.getenv("ALIBABA_APP_KEY")
APP_SECRET = os.getenv("ALIBABA_SECRET")
TOKEN = os.getenv("ALIBABA_TOKEN")
API_URL = "https://api.1688.com/router/rest"

def search_by_image(img_url, page=1, page_size=20):
    """
    1688拍立淘图片搜索
    """
    params = {
        "method": "1688.item_search_img",
        "app_key": APP_KEY,
        "access_token": TOKEN,
        "imgid": img_url,  # 图片URL，需先上传获取
        "page": page,
        "page_size": page_size,
        "sort": "sale",  # 按销量排序
        "timestamp": int(time.time())
    }
    
    # 生成签名（根据1688签名规则）
    # ... 签名逻辑省略 ...
    
    response = requests.post(API_URL, data=params, timeout=30)
    return response.json()

def parse_results(data):
    """
    解析并打印搜索结果
    """
    if data.get("code") != 200:
        print(f"请求失败: {data.get('msg')}")
        return
    
    items = data["items"]["item"]
    print(f"共找到 {len(items)} 个商品：\n")
    
    for idx, item in enumerate(items, 1):
        # 处理价格（兼容两种格式）
        price = item.get("price")
        if isinstance(price, dict):
            price_str = f"{price['min_price']}-{price['max_price']}"
        else:
            price_str = price
            
        similarity = item.get("similarity") or item.get("similarity_score", 0)
        
        print(f"{idx}. {item['title']}")
        print(f"   价格: ¥{price_str}  销量: {item.get('sales', 0)}")
        print(f"   相似度: {similarity:.1%}  起订量: {item.get('moq', 1)}件")
        print(f"   链接: {item['detail_url']}\n")

# 使用示例
if __name__ == "__main__":
    image_url = "https://img.alicdn.com/imgextra/...your_image.jpg"
    result = search_by_image(image_url, page_size=5)
    parse_results(result)

十、注意事项

图片要求：支持JPG/PNG/WEBP格式，单张≤5MB，建议清晰、完整、主体突出
权限申请 ：需先在1688开放平台申请item_search_img接口权限
频率限制：普通用户有QPS限制，企业认证用户可达每秒10+次调用
数据缓存：建议对高频搜索结果做Redis缓存，提升响应速度
翻页限制 ：pagecount超过200页时建议换图或细分类目再搜