一、 核心接口选型：item_search_img
要实现这一功能，我们使用的是OneBound提供的 1688.item_search_img 接口。该接口模拟了1688客户端的“拍照搜索”逻辑。
- 接口名称：
1688.item_search_img - 请求地址：
https://api-gw.onebound.cn/1688/item_search_img - 核心能力：接收图片URL，返回1688平台上的相似商品列表及详细数据。
二、 接入前的准备工作
在编写代码之前，你需要完成以下步骤：
- 注册开发者账号：前往 OneBound (万邦) 开放平台注册并获取
Key和Secret。 - 图片预处理：API目前仅支持图片URL参数。如果你的图片在本地，需要先将其上传到公网服务器获取链接，或者使用支持Base64的SDK（具体视平台最新版本而定，本文档示例基于URL参数）。
三、 核心参数详解
根据官方文档，调用该接口需要传递以下关键参数：
| 参数名 | 类型 | 是否必须 | 说明 |
|---|---|---|---|
| key | String | 是 | 你申请的API调用Key |
| imgid | String | 是 | 图片地址 (URL编码)。例如：https://img.alicdn.com/... |
| sort | String | 否 | 排序方式。如 sale-desc (销量降序)、bid2 (总价) |
| cache | String | 否 | 是否使用缓存 (yes/no)，默认yes，速度更快 |
注意：
imgid参数直接填入图片的网络地址。如果图片防盗链，可能需要先下载再上传到图床。
四、 Python 实战代码示例
以下代码展示了如何通过Python发送GET请求，并解析返回的JSON数据。
1. 安装依赖
pip install requests
2. 完整代码
import requests
import urllib.parse
import json
def search_1688_by_image(image_url, api_key, api_secret):
"""
通过图片URL搜索1688商品
:param image_url: 本地或网络图片的URL（需可被API服务器访问）
:param api_key: OneBound平台的Key
:param api_secret: OneBound平台的Secret
:return: 解析后的JSON数据
"""
# 1. 对图片URL进行URL编码，防止特殊字符报错
encoded_img_url = urllib.parse.quote(image_url, safe='')
# 2. 构造请求URL
# 注意：部分参数如secret可能在URL中传递，生产环境建议使用POST或鉴权SDK
url = f"https://api-gw.onebound.cn/1688/item_search_img/"
# 请求参数
params = {
'key': api_key,
'secret': api_secret, # 注意安全，勿泄露
'imgid': encoded_img_url, # 核心图片参数
'cache': 'yes', # 启用缓存加速
'result_type': 'json'
}
headers = {
"Accept-Encoding": "gzip",
"Connection": "close"
}
try:
# 3. 发送GET请求
response = requests.get(url, params=params, headers=headers, timeout=10)
response.raise_for_status() # 检查HTTP错误
data = response.json()
# 4. 解析数据
if data.get('error_code') == '0000':
print(f"搜索成功，共找到 {data['items']['total_results']} 个结果")
return parse_search_results(data['items']['item'])
else:
print(f"API调用失败: {data.get('reason')} [Code: {data.get('error_code')}]")
return None
except requests.exceptions.RequestException as e:
print(f"网络请求异常: {e}")
return None
def parse_search_results(raw_items):
"""
清洗和格式化返回的商品数据
"""
results = []
for item in raw_items:
result = {
'商品标题': item.get('title'),
'商品ID': item.get('num_iid'),
'价格': item.get('price'),
'销量': item.get('sales', 'N/A'),
'图片链接': item.get('pic_url'),
'详情页': item.get('detail_url'),
'是否一件代发': item.get('one_psale'),
'是否精选货源': item.get('is_jxhy')
}
results.append(result)
return results
# --- 执行脚本 ---
if __name__ == "__main__":
# 请替换为你的实际参数
API_KEY = "YOUR_ONEBOUND_API_KEY"
API_SECRET = "YOUR_ONEBOUND_API_SECRET"
# 测试图片URL (示例为篮球袜，来自文档)
# 你可以替换为任何1688商品的实拍图URL
TEST_IMAGE_URL = "http://g-search3.alicdn.com/img/bao/uploaded/i4/O1CN01IDpcD81zHbpHs1YgT_!!2200811456689.jpg"
# 调用函数
goods_data = search_1688_by_image(TEST_IMAGE_URL, API_KEY, API_SECRET)
if goods_data:
# 打印前3个结果预览
print(json.dumps(goods_data[:3], ensure_ascii=False, indent=2))
五、 返回数据结构解析
调用成功后，API返回标准JSON。根据文档示例，核心数据结构如下：
{
"items": {
"total_results": 670, // 总搜索结果数
"item": [
{
"title": "斗牛2.0篮球袜长筒男实战...",
"price": "4.50",
"sales": 25452, // 销量
"num_iid": 741422477524, // 商品ID
"pic_url": "https://cbu01.alicdn.com/...",
"detail_url": "https://detail.1688.com/offer/..."
}
]
},
"error_code": "0000" // 0000代表成功
}
关键字段提取：
num_iid：这是商品的唯一ID，可用于后续调用item_get接口获取更详细的库存和SKU信息。one_psale：布尔值，判断是否支持“一件代发”，这对无货源电商非常重要。is_jxhy：判断是否为“精选货源”，通常代表厂家直供，质量较有保障。
六、 常见错误码与解决方案
在实际调试中，如果遇到问题，请参考官方文档的错误码表：
| 错误码 | 含义 | 解决方案 |
|---|---|---|
| 0000 | success | 调用成功 |
| 2000 | Search success but no result | 图片未匹配到商品，尝试更换更清晰的实物图 |
| 4003 | Param error | 检查 imgid 参数是否为空或URL格式错误 |
| 4005 | Invalid authentication credentials | Key或Secret填写错误 |
| 4008 | API rate limit exceeded | 调用频率超限，降低请求频率 |
七、 进阶应用场景
- 本地图片上传：
如果你手里是本地图片（Bytes），需要先将其转换为URL。可以使用OneBound的upload_img接口，或者先上传至COS/OSS等对象存储服务，再将生成的URL传给item_search_img。 - 结合OCR识别：
对于包装盒或带有文字的图片，可以先调用img2text(图片识别商品接口) 提取关键词，再结合item_search进行文本+图片的混合搜索，提高准确率。 - 批量监控：
将此脚本加入定时任务（Crontab），定期扫描竞品图片，监控其在1688上的上新情况和价格波动。
作者： 供应链数据工程师
版权声明： 转载请注明出处。
互动： 你尝试用代码搜过什么有趣的商品？欢迎在评论区分享你的搜索结果！
