唯品会以图搜图（拍立淘）API接口调用指南详解

一、接口功能与适用场景

唯品会以图搜图（拍立淘）API接口基于图像识别技术，允许开发者通过上传商品图片快速搜索相似或同款商品。其核心功能包括：

• 精准匹配：提取图片特征，在唯品会商品库中匹配相似商品。
• 多维度返回：支持商品标题、价格、销量、链接、图片等信息的返回。
• 灵活调用：适用于电商比价、设计灵感搜索、个性化推荐等场景。

二、调用流程与步骤

1. 注册与认证
   • 注册开发者账号：在唯品会开放平台（或第三方聚合平台如万邦开放平台）注册账号。
   • 创建应用：登录后创建应用，获取API调用所需的key和secret（即API密钥和密钥）。
   • 权限确认：确保应用已开通以图搜图接口权限。
2. 图片准备与上传
   • 图片要求：
     • 格式：支持JPEG、PNG等常见格式。
     • 尺寸：建议清晰、无水印、商品主体突出（如避免背景干扰）。
     • 来源：若图片存储在外部服务器，需先调用唯品会上传图片接口（如upload_img）获取图片URL。
   • 上传方式：
     • 直接使用唯品会图片服务器URL（若图片已上传）。
     • 通过接口上传外部图片，获取返回的imgid（图片唯一标识）。
3. 构造请求

   • 请求方式：通常为HTTP GET请求。

   • 请求地址：

     https://api-gw.onebound.cn/vip/item_search_img/

   • 请求参数：

     参数名	类型	必填	描述
     key	String	是	调用key（拼接在URL中）
     secret	String	是	调用密钥
     imgid	String	是	图片URL或ID（需先上传图片）
     page_token	String	否	翻页参数（第一页不传，后续按返回的page_token传值）
     cache	String	否	是否使用缓存（默认yes，速度较快）
     result_type	String	否	返回格式（默认json，支持jsonu、xml等）

   • 示例请求：

     bash

     https://api-gw.onebound.cn/vip/item_search_img/?key=<您的key>&secret=<您的secret>&imgid=/xupload.vip.com/38444a01-e842-49bc-99c7-5267f6d36628_1726122211035_tmp_search.jpg

4. 发送请求与处理响应
   • 发送请求：使用HTTP客户端（如Python的requests库）发送请求。
   • 响应解析：
     • 成功响应（HTTP状态码200）：返回JSON格式数据，包含商品列表及分页信息。

       json

       {

       "items": {

       "real_total_results": 100,

       "total_results": 10,

       "page_count": 5,

       "page": "1",

       "page_size": "12",

       "page_token": "eyJvZmZzZXQiOjEyLCJzaXplIjoxMiwiaWR...",

       "item": [

       {

       "title": "夏季款中老年女装连帽外套",

       "pic_url": "http://d.vpimg1.com/upcb/gc000/2024/0307/104/ias_01a749f11b3191bfc60c9462c951be4f.jpg",

       "price": "498",

       "promotion_price": "64",

       "sales": "0",

       "num_iid": "6920347616300329372",

       "detail_url": "https://detail.vip.com/detail-1710614812-6920347616300329372.html"

       }

       ]

       }

       }

     • 错误响应：返回错误代码及描述（如401未授权、404图片不存在）。
5. 分页处理
   • 若搜索结果较多，需通过page_token参数分页获取数据。
   • 示例：第一页返回的page_token需作为第二页请求的参数。

三、代码示例（Python）

python

import requests

# 替换为实际参数

key = "<您的key>"

secret = "<您的secret>"

imgid = "/xupload.vip.com/38444a01-e842-49bc-99c7-5267f6d36628_1726122211035_tmp_search.jpg"

# 构造请求URL

url = f"https://api-gw.onebound.cn/vip/item_search_img/?key={key}&secret={secret}&imgid={imgid}"

# 发送请求

response = requests.get(url)

# 处理响应

if response.status_code == 200:

data = response.json()

items = data.get("items", {}).get("item", [])

for item in items:

print(f"商品标题: {item['title']}")

print(f"价格: {item['price']}")

print(f"链接: {item['detail_url']}")

else:

print(f"请求失败，状态码: {response.status_code}")

print(f"错误信息: {response.text}")

四、注意事项

1. 调用频率限制：
   唯品会API对调用频率有限制（如每分钟/每天次数），超限可能被封禁。需合理控制请求频率。

2. 图片质量要求：
   模糊、遮挡或背景复杂的图片可能导致搜索结果不准确。建议使用高清、主体突出的图片。

3. 数据安全与隐私：

   • 避免在请求中传递敏感信息（如用户隐私数据）。
   • 遵守唯品会平台规定及法律法规。

4. 接口更新与文档：
   唯品会可能更新接口参数或返回值格式，需定期查阅官方文档或联系技术支持。

5. 错误处理：

   • 捕获网络异常（如超时、连接失败）。
   • 根据错误代码（如401、429）调整请求或重试。

五、常见问题

1. Q：返回结果为空或不准？
   • A：检查图片质量，确保商品主体清晰。
   • A：确认图片已成功上传至唯品会服务器（imgid是否有效）。
2. Q：如何提高搜索效率？
   • A：限定商品类目（若接口支持cat参数）。
   • A：使用缓存（cache=yes）减少重复计算。
3. Q：接口支持哪些语言调用？
   • A：支持PHP、Java、Python、C#等多种语言，示例代码见万邦开放平台文档。