在电商系统开发或货源查找工具中，按图搜索商品是一项非常实用的功能。1688平台作为国内领先的B2B电商平台，提供了官方的按图搜索商品API接口。本文将详细讲解如何调用该接口。
一、 接口概述
该API允许开发者通过上传商品图片，检索1688平台上与之相似的商品列表。其核心功能是图像识别与商品匹配。
二、 准备工作
获取API权限
访问1688开放平台注册开发者账号。
创建应用，获取 App Key 和 App Secret。
在应用权限中申请 按图搜索商品 接口权限。
图片要求
图片格式支持：JPG, JPEG, PNG。
图片大小：建议小于1MB。
图片尺寸：建议最小边 ≥ 256像素，清晰无过多干扰元素。
三、 API调用详解
https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.image.search
参数名 类型 是否必填 说明
access_token String 是 用户授权后的令牌，通过 App Key 和 App Secret 换取。
image File 是 需要搜索的商品图片文件。
page Int 否 页码，默认1。
pageSize Int 否 每页记录数，默认20，最大50。
similarDegree Float 否 相似度阈值（0~1），仅返回相似度大于此值的商品，默认无限制。
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder
替换为你的实际信息
app_key = 'your_app_key'
app_secret = 'your_app_secret'
access_token = 'your_access_token' # 需要通过OAuth2流程获取
image_path = '/path/to/your/product.jpg'
构建请求URL
url = 'https://gw.open.1688.com/openapi/param2/1/com.alibaba.product/alibaba.product.image.search'
构建Multipart/form-data请求体
multipart_data = MultipartEncoder(
fields={
'access_token': access_token,
'image': ('image.jpg', open(image_path, 'rb'), 'image/jpeg'), # 注意字段名和文件名
'page': '1',
'pageSize': '20',
'similarDegree': '0.7'
}
)
设置请求头
headers = {
'Content-Type': multipart_data.content_type
}
发送请求
response = requests.post(url, data=multipart_data, headers=headers)
处理响应
if response.status_code == 200:
result = response.json()
# 解析返回的商品列表数据
print(result)
else:
print(f"请求失败，状态码: {response.status_code}")
四、 响应解析
成功调用后，接口返回JSON格式数据。主要结构如下：
{
"result": {
"success": true,
"productList": [
{
"productId": "商品ID",
"title": "商品标题",
"imageUrl": "商品主图URL",
"similarity": 0.85, // 与查询图片的相似度
"price": "价格",
"minOrderQuantity": "最小起订量",
"sellerId": "卖家ID",
"sellerName": "卖家名称",
"detailPageUrl": "商品详情页链接"
},
// ... 更多商品
],
"totalResults": 100, // 匹配到的商品总数
"page": 1,
"pageSize": 20
},
"errorCode": "0", // 0表示成功
"errorMessage": "success"
}
五、 注意事项
访问频率限制： 注意开放平台的调用频次限制，避免触发流控。
图片质量： 图片清晰度和主体突出程度直接影响搜索结果质量。
错误处理： 需处理常见错误码，如 400（参数错误）、401（认证失败）、500（服务端错误）等。
分页处理： 合理使用 page 和 pageSize 参数获取更多结果。
授权管理： access_token 有过期时间，需实现令牌的刷新机制。
六、 应用场景
电商比价工具
供应链货源查找
商品侵权检测
移动端拍照找货应用
通过合理调用此API，开发者可以高效地整合1688的海量商品资源，为用户提供便捷的以图搜货服务。
提示： 具体参数名称、值范围、错误码等请务必以1688开放平台官方文档最新说明为准。在开发前，建议先用平台提供的测试账号和工具进行调试。
