一张图片直接搜出 1688 上的同款与相似货源并拿到批发价、起订量、工厂标识——这就是「拍立淘」接口1688.item_search_img的价值。本文从接口原理到签名、参数、返回字段、代码落地、踩坑排错一次讲透可直接用于跨境选品、ERP 比价、供应链寻源等系统。一、为什么需要「以图搜货」做电商选品、跨境铺货、供应链比价的朋友几乎都遇到过同一个痛点手里只有一张图没有商品 ID也没有关键词。看到竞品爆款想知道 1688 上有没有同款、拿货价多少客户发来一张样品照片要找能做的工厂批量铺货时一张张图片手动搜、手动比价效率极低。传统关键词搜索做不到这一点因为关键词匹配的是文本而商品真正的信息在图片里。1688.item_search_img俗称「拍立淘」解决的正是这个问题它接收一张图片通过深度学习模型提取颜色、纹理、形状等视觉特征与 1688 商品库中的特征向量做比对返回同款 / 相似款 结构化数据。相比 C 端淘宝拍立淘1688 的拍立淘接口额外返回B2B 批发专属字段起订量MOQ、阶梯价、工厂标识、是否支持一件代发、发货地、30 天批发销量等——这才是做生意的关键信息。二、接口能力速览项目说明接口标识1688.item_search_img别名拍立淘、以图搜货、图片搜索商品请求方式GET / POST推荐 POST传 Base64 更稳请求地址https://api.1688.com/router/rest官方网关HTTPS图片传入方式① 公网图片 URL ② 图片 Base64 编码返回格式JSON鉴权方式AppKey AppSecret 签名MD5 / HMAC核心输出同款 / 相似款商品列表 相似度分数 批发字段一个典型的调用流程如下裁剪主体/压缩/转格式similarity 过滤本地图片图片预处理公网 URL 或 Base64构造公共参数按规则生成 sign 签名POST 请求网关返回 JSON同款/相似款筛选取 num_iid 调商品详情接口补全 SKU/阶梯价/库存比价表 / 入库 / 铺货三、接入前准备图片规范决定成败很多人接口调通了但匹配结果很差90% 的原因出在图片上。原图识别是「垃圾进垃圾出」务必先做预处理。3.1 图片硬性规范项目规范禁忌格式JPG / JPEG、PNGGIF、WebP、透明底 PNG、拼图、长截图大小≤ 1MB最大不超过 4MB超过 5MB 直接 413 报错分辨率最小边 ≥ 256px推荐 720–800px缩略小图、模糊截图画面商品主体居中主体占画面 60%少水印少杂物大面积水印、多件混拍、背景杂乱、纯文字图3.2 传图二选一方式一公网图片 URL推荐直接传图片地址减少 Base64 编解码异常。注意图片服务器不能有防盗链否则 1688 服务端拉不到图URL 中的特殊字符要做 URL 编码。方式二图片 Base64需要去掉data:image/jpg;base64,前缀并清除所有换行和空格否则会报参数错误。3.3 图片预处理建议提升匹配率的关键自动裁剪主体用主体检测把商品从背景中抠出来白底图识别效果最好去水印水印会干扰特征提取能用原图就别用带水印的图压缩单张控制在 500KB 左右兼顾清晰度与传输速度统一格式批量任务统一转成 JPG避免格式参差导致失败。四、核心参数详解4.1 公共参数必填参数是否必填说明method是固定值1688.item_search_imgapp_key是开放平台应用 Keytimestamp是时间戳毫秒级与平台服务器时间误差不能太大v是固定2.0format是固定jsonsign_method是固定md5或 HMAC-SHA256sign是按规则生成的签名见第五节4.2 业务参数参数是否必填说明imgid是图片 URL 或清洗后的 Base64 字符串二选一search_type否1 优先同款默认0 相似款page否页码默认 1page_size否每页条数默认 20最大 50 / 100视服务商而定cat否1688 类目 ID有明确类目时传入可减少无关货源选品实战小技巧先传search_type1找同款找不到再切0找相似替代件。五、签名生成原理阿里开放平台体系使用「参数排序 首尾包裹密钥 MD5 大写」的经典签名规则步骤如下把所有业务参数和公共参数sign除外按key 字典序排序依次拼接为key1value1key2value2...在拼接串头部和尾部各加一次app_secret对最终字符串做MD5转大写即为sign。一眼看懂sign MD5( secret key1value1key2value2... secret ).upper()六、Python 完整实战下面是一套「以图搜货 过滤 拉详情 导出 CSV」的完整代码复制即可跑。6.1 安装依赖pipinstallrequests pandas6.2 核心代码importhashlibimporttimeimportjsonimportbase64importrequestsimportpandasaspd# 1. 配置区替换成你自己的密钥APP_KEYyour_app_keyAPP_SECRETyour_app_secretGATEWAYhttps://api.1688.com/router/rest# 2. 签名生成 defbuild_sign(params:dict,secret:str)-str:按阿里开放平台规则生成签名字典排序 - 拼接 - 首尾包 secret - MD5 大写sorted_keyssorted(params.keys())sign_str.join(f{k}{params[k]}forkinsorted_keys)sign_strsecretsign_strsecretreturnhashlib.md5(sign_str.encode(utf-8)).hexdigest().upper()# 3. 本地图片转 Base64可选defimage_to_base64(image_path:str)-str:withopen(image_path,rb)asf:b64base64.b64encode(f.read()).decode(utf-8)# 注意不要加 data:image/jpg;base64, 前缀returnb64.replace(\n,).replace(\r,).strip()# 4. 以图搜货主函数 defsearch_by_image(img_url:strNone,img_base64:strNone,search_type:int1,page:int1,page_size:int20,cat:strNone)-dict:ifnotimg_urlandnotimg_base64:raiseValueError(必须提供 img_url 或 img_base64 其中之一)params{method:1688.item_search_img,app_key:APP_KEY,timestamp:str(int(time.time()*1000)),# 毫秒时间戳v:2.0,format:json,sign_method:md5,imgid:img_urlifimg_urlelseimg_base64,search_type:search_type,page:page,page_size:page_size,}ifcat:params[cat]cat params[sign]build_sign(params,APP_SECRET)resprequests.post(GATEWAY,dataparams,timeout15)resp.raise_for_status()returnresp.json()# 5. 解析结果 defparse_items(data:dict,similarity_threshold:float0.7)-pd.DataFrame:items(data.get(items)or{}).get(item)or[]rows[]foritinitems:simfloat(it.get(similarity,0)or0)rows.append({num_iid:it.get(num_iid),title:it.get(title),price:it.get(price),moq:it.get(moq),sales:it.get(sales),similarity:sim,seller_name:it.get(seller_name),detail_url:it.get(detail_url),tag:同款ifsim0.8else(相似ifsim0.6else存疑),})dfpd.DataFrame(rows)ifnotdf.empty:dfdf[df[similarity]similarity_threshold]dfdf.sort_values(similarity,ascendingFalse).reset_index(dropTrue)returndf# 6. 主流程 if__name____main__:# 方式一直接用公网图片 URLresultsearch_by_image(img_urlhttps://cbu01.alicdn.com/img/ibank/example.jpg,search_type1,# 1同款0相似款page1,page_size20,)# 方式二本地图片转 Base64二选一即可# b64 image_to_base64(./sample.jpg)# result search_by_image(img_base64b64, search_type1)print(返回状态:,result.get(code),result.get(msg))dfparse_items(result,similarity_threshold0.7)print(df.to_string(indexFalse))# 导出比价表ifnotdf.empty:df.to_csv(1688_pailitao_result.csv,indexFalse,encodingutf-8-sig)print(已导出 1688_pailitao_result.csv)6.3 结果示例控制台返回状态: 200 success num_iid title price moq sales similarity seller_name tag 0 728510689123 2025夏新款真丝连衣裙 128.00 2 327 0.92 杭州XX服饰工厂 同款 1 728510776655 真丝雪纺连衣裙批 95.50 3 189 0.85 绍兴XX纺织 同款 2 728510812345 仿真丝连衣裙 一件代发 68.00 1 56 0.73 义乌XX服饰 相似6.4 联动「商品详情接口」补全采购字段拍立淘只返回基础信息不包含阶梯价、样品费、交期等。拿到num_iid后再调商品详情接口批量补全defget_item_detail(num_iid:str)-dict:params{method:1688.item_get,# 详情接口app_key:APP_KEY,timestamp:str(int(time.time()*1000)),v:2.0,format:json,sign_method:md5,num_iid:num_iid,}params[sign]build_sign(params,APP_SECRET)resprequests.post(GATEWAY,dataparams,timeout15)returnresp.json()# 对搜到的 Top N 商品批量拉详情foriidindf[num_iid].head(5):detailget_item_detail(iid)# detail 中可拿到阶梯批发价、SKU、库存、重量、材质、发货时效等七、返回字段全解析7.1 顶层结构{code:200,msg:success,request_id:12345abcde,items:{page:1,real_total_results:670,total_results:670,pagecount:14,page_size:50,item:[...]}}字段类型说明codeInteger状态码200 / 0 表示成功以服务商文档为准msgString状态描述失败时给出错误原因request_idString请求唯一标识用于问题追踪与日志定位items.pageString当前页码items.real_total_resultsInteger实际库中命中同款 相似款总量items.total_resultsInteger本次可翻页总量items.pagecountInteger总页数items.page_sizeString每页条数items.itemArray商品数组见下表7.2 单个商品字段item[]字段类型示例业务含义num_iidString728510689123商品数字 ID用于调详情接口titleString2025夏新款真丝连衣裙商品标题pic_urlStringhttps://cbu01.alicdn.com/...商品主图1688 压缩图priceFloat/String128.00批发价 / 代发价元price_rangeObject{min_price:95,max_price:135}多 SKU 时的价格区间unitString件计价单位moqInt2最小起订量MOQsalesInt327近 30 天已售件数similarityFloat0.87图片相似度 0~1 0.8 可视为同款seller_nameString杭州XX服饰工厂店铺名称detail_urlStringhttps://detail.1688.com/...商品详情页链接delivery_placeString浙江 义乌发货地重点字段similarity相似度—— 这是整个接口最核心的字段可以据此写死筛选规则 0.7丢弃匹配偏差太大0.7 ~ 0.8相似款人工复核≥ 0.8高度同款自动进入成本核算流程。八、五大落地场景场景 1跨境选品 / 无货源铺货海外平台看到爆款 → 截图 → 拍立淘找 1688 同款 → 过滤贸易商、优先工厂店 → 校验是否支持一件代发 → 调详情算到手价与毛利 → 一键铺货。场景 2企业采购寻源 / 样品比价采购手里只有样品照片 → 拍立淘匹配同款和相似替代件 → 组装比价表 → 高相似度直接对接工厂打样。场景 3商品溯源 / 侵权排查品牌方用商品图反查 1688 上的疑似侵权货源定位店铺与商品链接。场景 4ERP / 供应链 SaaS 集成将拍立淘能力嵌入 ERP、选品系统把「图搜 → 详情 → 比价 → 入库」串成自动化流水线。场景 5批量图库匹配电商运营有一批商品图需要批量找到对应货源用异步队列跑拍立淘结果落库做持续监控。九、性能优化与踩坑排错9.1 常见报错与原因现象可能原因解决413 超限图片超过大小限制压缩到 1MB 以内参数错误Base64 带了data:image/...;base64,前缀去掉前缀、清除换行空格匹配结果为空/偏差大图片有水印、多件混拍、背景杂乱裁剪主体、去水印、换白底图拉不到图图片服务器有防盗链先下载再上传到自己的图床 / OSS签名错误参数未排序 / 未首尾包 secret / 未转大写严格按签名规则重写429 / 限流并发过高或超出配额做限流、加缓存、异步队列9.2 优化建议必须做异步任务队列批量选品不要并发猛攻接口否则一定触发限流相同图片做本地缓存短时间内重复检索直接读缓存节省调用额度图片预处理前置自动裁剪 去水印 压缩到 500KB 左右匹配率提升最明显结果去重同一num_iid可能在多次搜索中重复出现入库前要去重相似度分级把similarity写成可配置阈值不同业务用不同标准。十、合规提示使用拍立淘接口时请务必遵守遵守 1688 开放平台开发者协议及数据使用规范不得将数据用于违法用途尊重知识产权不得用于批量抓取、恶意爬取或侵犯他人商标/著作权的行为图片素材应确保来源合法避免上传涉密、侵权或违规图片涉及个人信息或交易数据时遵循《个人信息保护法》《数据安全法》等相关法规合理控制调用频率避免对平台造成压力。十一、总结1688.item_search_img把「一张图」变成「一批结构化货源」是做选品、比价、寻源、铺货的核心能力。落地要点浓缩成四句话图片预处理是成败关键——裁剪、去水印、压到 500KB白底主体图最好签名规则记牢——排序、拼接、首尾包 secret、MD5 大写相似度是灵魂字段——用 0.7 / 0.8 两级阈值做自动筛选拍立淘 详情接口组合出击——图搜拿 ID详情补 SKU、阶梯价、库存才能做出完整比价表。掌握这套打法就能把「以图搜货」真正接入到自己的选品与供应链系统里。关于接入如果你没有企业资质、不想自己处理签名与限流也可以通过第三方聚合 API 服务商快速接入免资质、开箱即用。有代采 / 转发 / 转售需求的朋友欢迎留言或私信交流可提供免费测试额度.