1688 以图搜货 API（item_search_img）开发
·
本贴只展示部分结构，「 技术、数据、接口、系统问题欢迎留言私信获取系统演示和API调用 」
在电商选品、比价、货源溯源、跨境铺货等实际业务中，图片搜商品已经成为刚需能力。相比关键词搜索，图片搜索不受标题、语种、类目限制，能直接匹配同款 / 相似货源，是 1688 找货最高效的方式之一。
1688 官方图片搜索能力封装为 item_search_img API，基于深度学习图像特征匹配，支持传入图片 URL 检索相似商品，并返回结构化商品数据。本文从真实开发场景出发，去掉 AI 式套话，补充技术细节、修复代码问题，提供可直接上线使用的调用方案与最佳实践。
一、API 核心能力与适用场景
item_search_img 是面向开发者的以图搜货标准接口，核心能力：
- 图像特征提取通过 CNN 卷积神经网络提取商品的颜色、纹理、轮廓、结构特征，生成特征向量，不受水印、角度、光线过度干扰。
- 亿级商品库实时匹配与 1688 全量商品库进行相似度计算，返回同款 / 相似款，支持按销量、价格、新品排序。
- 结构化数据输出直接返回商品 ID、标题、价格、厂家、销量、店铺类型、商品链接等标准字段，无需解析网页。
真实适用场景
- 电商一键找同款货源
- 跨境独立站反向溯源 1688 供应商
- 价格监控与竞品比价
- 选品工具批量挖掘工厂货源
- ERP / 打单系统图片识别商品
二、接入准备（开发者必看）
1. 账号与权限
- 注册开放平台 / 聚合 API 平台账号（如 OneBound、阿里云 API 市场）
- 完成企业 / 个人认证，创建应用
- 获取调用凭证：
API Key+Secret
2. 图片规范（决定匹配准确率）
- 必须是公网可访问 URL（本地图片需上传 OSS / 图床）
- 推荐：主体居中、无多余背景、清晰度高、无大面积遮挡
- 支持：JPG/PNG/WebP，大小不超过 4MB
- 不建议：截图、模糊图、拼接图、纯文字图
3. 必备前置知识
- URL 编码：图片地址必须编码（特殊字符如
/?&会导致请求失败） - 接口限流：大多数平台限制 QPS=5~10，需做限流与重试
- 签名机制：部分环境需要 MD5 签名校验
三、API 接口完整说明
请求信息
- 请求地址：
https://api-gw.onebound.cn/1688/item_search_img - 请求方式：
GET（推荐）/POST - 数据格式：
JSON
核心参数（完整版）
表格
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 平台分配的 API 密钥 |
| secret | string | 是 | 签名密钥 |
| imgid | string | 是 | URL 编码后的图片地址 |
| sort | string | 否 | 排序：sale-desc销量降序 /price-asc价格升序 |
| page | int | 否 | 页码，默认 1 |
| page_size | int | 否 | 每页条数，最大 40 |
通用返回结构
{
# API测试、系统演示控制台：http://console.open.onebound.cn/console/?i=Rookie
"error_code": "0000",
"reason": "ok",
"items": {
"total_results": 128,
"item": [
{
"title": "商品标题",
"price": "19.5",
"sales": "2000+",
"img_url": "图片",
"detail_url": "1688商品链接",
"company_name": "工厂/店铺名",
"is_factory": true
}
]
}
}四、多语言实战代码（可直接生产使用）
1. Python 完整版（含异常处理 + 编码 + 重试）
import requests
import urllib.parse
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
# 配置信息
API_KEY = "你的API_KEY"
API_SECRET = "你的SECRET"
IMAGE_URL = "https://example.com/your-product.jpg"
def search_1688_by_image(img_url, page=1, page_size=20, sort="sale-desc"):
"""
1688图片搜索API（稳定生产版）
"""
# 图片地址必须URL编码
encoded_img = urllib.parse.quote(img_url)
# 请求参数
params = {
"key": API_KEY,
"secret": API_SECRET,
"imgid": encoded_img,
"sort": sort,
"page": page,
"page_size": page_size
}
# 重试策略（应对限流/网络波动）
session = requests.Session()
retry = Retry(total=3, backoff_factor=1, status_forcelist=[429, 500, 502, 503])
session.mount("https://", HTTPAdapter(max_retries=retry))
try:
url = "https://api-gw.onebound.cn/1688/item_search_img"
resp = session.get(url, params=params, timeout=15)
resp.raise_for_status()
data = resp.json()
if data.get("error_code") == "0000":
return {
"total": data["items"]["total_results"],
"items": data["items"]["item"]
}
else:
return {"error": data.get("reason", "调用失败")}
except Exception as e:
return {"error": f"请求异常：{str(e)}"}
# 调用示例
if __name__ == "__main__":
result = search_1688_by_image(IMAGE_URL)
if "items" in result:
print(f"匹配到 {result['total']} 个商品")
for item in result["items"][:5]:
print(f"【商品】{item['title']}")
print(f"【价格】{item['price']} 元")
print(f"【销量】{item['sales']}")
print("-"*50)
else:
print(result["error"])2. Java 生产版（OkHttp + 编码 + 异常处理）
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import java.net.URLEncoder;
import java.util.concurrent.TimeUnit;
public class _1688ImageSearch {
private static final String API_KEY = "你的API_KEY";
private static final String SECRET = "你的SECRET";
public static JSONObject search(String imageUrl) {
try {
OkHttpClient client = new OkHttpClient.Builder()
.connectTimeout(10, TimeUnit.SECONDS)
.readTimeout(15, TimeUnit.SECONDS)
.build();
String encodedImg = URLEncoder.encode(imageUrl, "UTF-8");
String url = "https://api-gw.onebound.cn/1688/item_search_img"
+ "?key=" + API_KEY
+ "&secret=" + SECRET
+ "&imgid=" + encodedImg
+ "&sort=sale-desc&page=1&page_size=20";
Request request = new Request.Builder().url(url).build();
Response response = client.newCall(request).execute();
String body = response.body().string();
JSONObject result = JSON.parseObject(body);
return result;
} catch (Exception e) {
JSONObject error = new JSONObject();
error.put("error", e.getMessage());
return error;
}
}
public static void main(String[] args) {
JSONObject res = search("https://example.com/your-product.jpg");
System.out.println(res.toJSONString());
}
}3. Node.js 版（Axios + 异步优雅写法）
const axios = require('axios');
const API_KEY = "你的API_KEY";
const SECRET = "你的SECRET";
async function searchByImage(imageUrl) {
try {
const encodedImg = encodeURIComponent(imageUrl);
const url = `https://api-gw.onebound.cn/1688/item_search_img`;
const res = await axios.get(url, {
params: {
key: API_KEY,
secret: SECRET,
imgid: encodedImg,
sort: "sale-desc",
page: 1,
page_size: 20
},
timeout: 15000
});
const data = res.data;
if (data.error_code === "0000") {
return {
total: data.items.total_results,
items: data.items.item
};
} else {
return { error: data.reason };
}
} catch (err) {
return { error: err.message };
}
}
// 测试调用
searchByImage("https://example.com/your-product.jpg")
.then(console.log)
.catch(console.error);五、关键技术要点（避坑必备）
1. 图片 URL 编码（90% 新手失败原因）
图片地址中如果包含 ? & # 等字符，必须编码，否则接口无法识别。
2. 接口限流与重试
- 错误码
429= 请求频率超限 - 必须使用指数退避重试
- 单账号 QPS 控制在 5 以内
3. 结果过滤（提升业务精准度）
- 过滤非工厂店（只保留
is_factory=true） - 过滤低销量商品
- 按价格区间筛选
- 按发货地筛选
4. 合规要求
- 不得使用侵权图片搜索
- 不得用于恶意比价、恶意爬取、恶意下单
- 商品数据仅限自身业务使用
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
2
0- 0
已为社区贡献3条内容
所有评论(0)