# 以图搜产品接口
## 调用整体流程
```
1. 提交图片 （/v3/api/open/ai-search/image/submit或/v3/api/open/ai-search/image/submit/image-url），得到 image_id
↓
2. 等待10-20秒
↓
3. 根据image_id查询处理状态（/v3/api/open/ai-search/image/status）
↓
4. 根据image_id获取结果摘要（/v3/api/open/ai-search/image/resultSummary）
↓
5. 根据摘要数据以及image_id，选择性调用详细列表接口：
- 产品列表：/v3/api/open/ai-search/image/product/search（本接口）
- 广告列表：/v3/api/open/ai-search/image/search4/ad/search
- 店铺列表：/v3/api/open/ai-search/image/root-path/search
- TikTok产品：/v3/api/open/ai-search/image/tiktok-product/search
- TikTok店铺：/v3/api/open/ai-search/image/tiktok-shop/search
```
## 接口概述
以图搜产品接口用于根据图片搜索相似的电商产品。需要先通过图片提交接口获取 `image_id`,然后使用该接口查询与图片相似的产品列表。
该接口支持丰富的过滤条件,包括平台类型、数据类型、地区、关键词、互动数据范围、时间范围等多维度筛选,帮助用户精准定位目标产品。
---
## 接口信息
- **接口名称**: 以图搜产品
- **请求方法**: POST
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/ai-search/image/product/search`
- **接口描述**: 根据图片ID查询相似产品,支持多维度过滤和排序
- **价格说明**: 获取一条数据结果消耗1 credit
**请求头:**
- Content-Type: application/json
- Accept: application/json
---
## 请求参数
### 请求结构
| 参数名 | 类型 | 描述 | 示例 | 必填 | 默认值 |
| ------ | ------ | --------------------------- | ------------------------------------------------- | ---- | ------ |
| key | string | 用户申请的外部 api 请求 key | "your_api_key_here" | 是 | |
| uri | string | 接口路径 | "/v3/api/open/ai-search/image/product/search" | 是 | |
| params | object | 接口入参对象 | 见参数列表 | 是 | |
### 请求体参数 (params 对象)
| 参数名 | 类型 | 必填 | 描述 |
|----------------------|---------|------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| image_id | String | 是 | 图片ID,通过图片提交接口获得。格式:img_开头+时间戳 |
| current_page | Integer | 是 | 当前页码,从1开始 |
| page_size | Integer | 是 | 每页数量 |
| plat_type | Integer | 否 | 平台类型 (0:全部, 1:tiktok, 2:facebook) |
| time | Integer | 否 | 时间范围 (0:全部, 1:昨天, 7:近7天, 30:近30天, 90:近90天) |
| keyword | String | 否 | 搜索关键词 |
| search_type | Integer | 否 | 搜索类型 (1:产品标题, 2:产品描述, 3:广告主URL, 4:广告主名, 5:产品关键词) |
| category | String | 否 | 产品分类ID列表,见 [电商分类](https://www.pipispy.com/zh/doc/others-product-category),使用逗号分隔多个分类ID |
| region | String | 否 | 地区列表,支持GB/US等地区代码,见 [国家地区](https://www.pipispy.com/zh/doc/others-region),使用逗号分隔多个地区 |
| play_count_min | Integer | 否 | 最小广告播放数 |
| play_count_max | Integer | 否 | 最大广告播放数 |
| digg_count_min | Integer | 否 | 最小点赞数 |
| digg_count_max | Integer | 否 | 最大点赞数 |
| digg_play_rate_min | Double | 否 | 最小点赞率 |
| digg_play_rate_max | Double | 否 | 最大点赞率 |
| comment_count_min | Integer | 否 | 最小评论数 |
| comment_count_max | Integer | 否 | 最大评论数 |
| share_count_min | Integer | 否 | 最小分享数 |
| share_count_max | Integer | 否 | 最大分享数 |
| video_count_min | Integer | 否 | 最小广告数量 |
| video_count_max | Integer | 否 | 最大广告数量 |
| put_day_min | Integer | 否 | 最小投放天数 |
| put_day_max | Integer | 否 | 最大投放天数 |
| create_time_start | Integer | 否 | 产品创建时间起始值(Unix时间戳,秒) |
| create_time_end | Integer | 否 | 产品创建时间结束值(Unix时间戳,秒) |
| tiktok_time_start | Integer | 否 | 广告开始日期,首次发现时间起始值(Unix时间戳,秒),需注意，这里并不是只指tiktok广告开始时间，前缀“tiktok”仅为命名习惯，无实际区分意义，也就是说当仅plat_type=2时，指的就是facebook广告开始时间，当plat_type=0,代表的是全部广告开始时间 |
| tiktok_time_end | Integer | 否 | 广告开始日期,首次发现时间结束值(Unix时间戳,秒),需注意，这里并不是只指tiktok广告开始时间结束值，前缀“tiktok”仅为命名习惯，无实际区分意义，也就是说当仅plat_type=2时，指的就是facebook广告开始时间结束值，当plat_type=0,代表的是全部广告开始时间结束值 |
| latest_found_time_start | Integer | 否 | 广告结束日期,最新发现时间起始值(Unix时间戳,秒) |
| latest_found_time_end | Integer | 否 | 广告结束日期,最新发现时间结束值(Unix时间戳,秒) |
| price_min | Double | 否 | 产品价格(USD),最小价格 |
| price_max | Double | 否 | 产品价格(USD),最大价格 |
| currency | String | 否 | 货币单位,使用逗号分隔多个货币 |
| platform | String | 否 | 平台标识,使用逗号分隔,支持:shopify、woocommerce、shoplazza、magento、wix、shopline、squarespace、shopyy |
| popular_person_count_min | Integer | 否 | 最小红人数量(仅plat_type=1时有效) |
| popular_person_count_max | Integer | 否 | 最大红人数量(仅plat_type=1时有效) |
| root_path | String | 否 | 广告主名 |
| id | String | 否 | 产品ID,使用逗号分隔多个ID |
| store_id | String | 否 | 店铺唯一标识ID,为13位字符串(例如:c2d5b2547218a),对应店铺榜单列表接口返回结果中的store_id字段 |
| after_id | String | 否 | 分页游标ID(用于深度分页) |
| after_key | String | 否 | 分页游标键值(用于深度分页) |
| sort | Integer | 否 | 排序方式:
当plat_type=0时
9-按相似度排序(默认)
0-总开始日期
1-总结束日期
2-产品创建时间
3-产品价格(USD)
4-总广告数
5-广告播放
6-总点赞数
7-投放天数
当plat_type=1时
9-按相似度排序(默认)
0-tiktok广告开始时间
1-tiktok广告结束时间
2-tiktok产品创建时间
3-tiktok产品价格(USD)
4-tiktok广告数
5-tiktok播放数
6-tiktok点赞数
7-tiktok投放天数
8-tiktok红人数
当plat_type=2时
9-按相似度排序(默认)
0-facebook广告开始时间
1-facebook广告结束时间
2-facebook产品创建时间
3-facebook产品价格(USD)
4-facebook广告数
5-facebook播放数
6-facebook点赞数
7-facebook投放天数 |
| sort_type | String | 否 | 排序类型 (asc:升序, desc:降序) |
## 请求示例
### 基础请求示例
#### 使用 cURL
```bash
curl -X POST "https://www.pipispy.com/open-api/v1/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/open/ai-search/image/product/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20
}
}'
```
### 高级过滤示例
#### 使用关键词和地区过滤
```bash
curl -X POST "https://www.pipispy.com/open-api/v1/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/open/ai-search/image/product/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20,
"plat_type": 1,
"region": "US,GB",
"keyword": "fashion",
"search_type": 2,
"play_count_min": 10000,
"sort": 0,
"sort_type": "desc"
}
}'
```
#### 按价格范围和分类过滤
```bash
curl -X POST "https://www.pipispy.com/open-api/v1/data" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"key": "your_api_key_here",
"uri": "/v3/api/open/ai-search/image/product/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20,
"price_min": 10,
"price_max": 100,
"category": "62739afc38365b2f72048ebe",
"time": 30,
"sort": 9
}
}'
```
## 响应参数
### 响应体结构
```json
{
"code": 200,
"message": "success",
"data": {
"data": [ ... ],
"page": { ... }
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
```
### 响应字段说明
#### 顶层字段
| 字段名 | 类型 | 描述 |
| --------- | ------- | ------------------------------------------------------ |
| code | Integer | 响应状态码,200 表示成功 |
| message | String | 响应消息 |
| data | Object | 响应数据,包含 data(产品列表)和 page(分页信息) |
| version | String | API 版本 |
| timestamp | String | 响应时间戳 |
| sign | String | 响应签名 |
| remaining_credits | Long | 当前请求后的剩余可用积分 |
| consumed_credits | Long | 本次请求消耗的积分 |
| success | Boolean | 请求是否成功 |
| fail | Boolean | 请求是否失败 |
#### 产品数据字段 (data)
| 字段名 | 类型 | 描述 |
| ------------------------- | ------------- | ------------------------------------------ |
| id | String | 产品唯一标识ID |
| title | String | 产品标题 |
| image | String | 产品主图片URL |
| price | Double | 产品价格 |
| currency | String | 产品价格货币类型 |
| usd_price | Double | 产品美元价格 |
| platform | String | 产品平台标识 |
| is_collection | Boolean | 是否已收藏 |
| create_time | Long | 产品创建时间戳 |
| tiktok_time | Long | TikTok平台首次发现时间戳 |
| found_time | Long | TikTok平台首次发现时间戳 |
| latest_found_time | Long | TikTok平台最新发现时间戳 |
| play_count | Long | TikTok平台播放量 |
| digg_count | Long | TikTok平台点赞数 |
| digg_play_rate | Double | TikTok平台点赞播放比 |
| comment_count | Long | TikTok平台评论数 |
| share_count | Long | TikTok平台分享数 |
| video_count | Long | TikTok平台视频数量 |
| put_days | Long | TikTok平台投放天数 |
| ad_platform_list | List\ | 广告平台列表(如:tiktok, facebook) |
| popular_person_count | Long | 达人数量 |
| facebook_data_count | Long | Facebook平台数据数量 |
| facebook_digg_count | Long | Facebook平台点赞数 |
| facebook_found_time | Long | Facebook平台首次发现时间戳 |
| facebook_latest_found_time| Long | Facebook平台最新发现时间戳 |
| facebook_put_days | Long | Facebook平台投放天数 |
| facebook_share_count | Long | Facebook平台分享数 |
| facebook_comment_count | Long | Facebook平台评论数 |
| all_data_count | Long | 全平台数据数量 |
| all_digg_count | Long | 全平台点赞数 |
| all_found_time | Long | 全平台首次发现时间戳 |
| all_latest_found_time | Long | 全平台最新发现时间戳 |
| all_put_days | Long | 全平台投放天数 |
| all_share_count | Long | 全平台分享数 |
| all_comment_count | Long | 全平台评论数 |
| sort_id | String | 排序ID(用于分页排序) |
#### 分页信息字段 (page)
| 字段名 | 类型 | 描述 |
| ------------ | ------- | ------------ |
| total_count | Long | 总记录数 |
| page_count | Long | 总页数 |
| current_page | Long | 当前页码 |
| page_size | Long | 每页大小 |
| is_next | Boolean | 是否有下一页 |
---
## 响应示例
```json
{
"code": 200,
"message": "success",
"data": {
"data": [
{
"id": "product_001",
"title": "Wireless Bluetooth Headphones",
"image": "https://cdn-product.pipispy.com/product_001.jpg",
"price": 29.99,
"currency": "USD",
"usd_price": 29.99,
"platform": "shopify",
"is_collection": false,
"create_time": 1700000000,
"tiktok_time": 1700086400,
"found_time": 1700086400,
"latest_found_time": 1737532800,
"play_count": 1523456,
"digg_count": 45678,
"digg_play_rate": 0.03,
"comment_count": 3456,
"share_count": 1234,
"video_count": 125,
"put_days": 45,
"ad_platform_list": ["tiktok", "facebook"],
"popular_person_count": 23,
"facebook_data_count": 56,
"facebook_digg_count": 12345,
"facebook_found_time": 1700172800,
"facebook_latest_found_time": 1737446400,
"facebook_put_days": 38,
"facebook_share_count": 567,
"facebook_comment_count": 890,
"all_data_count": 181,
"all_digg_count": 58023,
"all_found_time": 1700086400,
"all_latest_found_time": 1737532800,
"all_put_days": 45,
"all_share_count": 1801,
"all_comment_count": 4346,
"sort_id": "product_001"
},
{
"id": "product_002",
"title": "Smart Watch Fitness Tracker",
"image": "https://cdn-product.pipispy.com/product_002.jpg",
"price": 49.99,
"currency": "USD",
"usd_price": 49.99,
"platform": "shopify",
"is_collection": true,
"create_time": 1699913600,
"tiktok_time": 1700000000,
"found_time": 1700000000,
"latest_found_time": 1737446400,
"play_count": 2345678,
"digg_count": 78901,
"digg_play_rate": 0.034,
"comment_count": 5678,
"share_count": 2345,
"video_count": 198,
"put_days": 52,
"ad_platform_list": ["tiktok"],
"popular_person_count": 45,
"facebook_data_count": 0,
"facebook_digg_count": 0,
"facebook_found_time": 0,
"facebook_latest_found_time": 0,
"facebook_put_days": 0,
"facebook_share_count": 0,
"facebook_comment_count": 0,
"all_data_count": 198,
"all_digg_count": 78901,
"all_found_time": 1700000000,
"all_latest_found_time": 1737446400,
"all_put_days": 52,
"all_share_count": 2345,
"all_comment_count": 5678,
"sort_id": "product_002"
}
],
"page": {
"total_count": 1000,
"page_count": 50,
"current_page": 1,
"page_size": 20,
"is_next": true
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 20,
"success": true,
"fail": false
}
```
---
## 错误码说明
| 错误码 | 描述 |
| ------ | --------------------- |
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 - API 密钥无效 |
| 500 | 服务器内部错误 |
---
## 相关接口
完整的以图搜产品流程涉及以下接口:
1. **图片提交**: `/v3/api/open/ai-search/image/submit` 或 `/v3/api/open/ai-search/image/submit/image-url`
2. **处理状态查询**: `/v3/api/open/ai-search/image/status`
3. **结果摘要**: `/v3/api/open/ai-search/image/resultSummary`
4. **广告搜索**: `/v3/api/open/ai-search/image/search4/ad/search`
5. **产品搜索**(本接口): `/v3/api/open/ai-search/image/product/search`
6. **店铺搜索**: `/v3/api/open/ai-search/image/root-path/search`
7. **TikTok产品搜索**: `/v3/api/open/ai-search/image/tiktok-product/search`
8. **TikTok店铺搜索**: `/v3/api/open/ai-search/image/tiktok-shop/search`
---
## 使用说明
1. **相似度排序**: 默认情况下(sort=9),产品列表按图片相似度降序排列,最相似的产品排在最前面
2. **平台筛选**: 使用 plat_type 参数可以筛选特定平台的产品数据
3. **时间范围**: 使用 time 参数可以获取指定时间范围内的产品数据
4. **关键词搜索**: 支持多种搜索类型,可按产品标题、描述、店铺URL等不同维度搜索
5. **地区过滤**: 支持多地区筛选,使用逗号分隔多个地区代码
6. **分类过滤**: 支持按产品分类筛选,需要使用正确的分类ID
7. **数据统计**: 返回结果包含 TikTok、Facebook 和全平台的完整统计数据