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

一、接口功能与适用场景

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

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

二、调用流程与步骤

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

构造请求

请求方式：通常为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 |

发送请求与处理响应
- 发送请求 ：使用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图片不存在）。
分页处理
- 若搜索结果较多，需通过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}") |

四、注意事项

调用频率限制 ：

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

模糊、遮挡或背景复杂的图片可能导致搜索结果不准确。建议使用高清、主体突出的图片。
数据安全与隐私：
- 避免在请求中传递敏感信息（如用户隐私数据）。
- 遵守唯品会平台规定及法律法规。
接口更新与文档 ：

唯品会可能更新接口参数或返回值格式，需定期查阅官方文档或联系技术支持。
错误处理：
- 捕获网络异常（如超时、连接失败）。
- 根据错误代码（如401、429）调整请求或重试。

五、常见问题

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