# 以图搜同款结果摘要接口
## 调用整体流程
```
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
```

## 接口信息

- **接口名称**: 获取以图搜同款结果摘要
- **请求方法**: GET
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/ai-search/image/resultSummary`
- **接口描述**: 获取图片搜索结果的统计摘要信息，包括搜索到的产品、广告、店铺等各类数据的数量统计。需要先调用图片提交接口获取 image_id，并等待图片处理完成后再调用此接口
- **价格说明**: 免费

**请求头:**

- Content-Type: application/json
- Accept: application/json

## 请求参数

### 请求结构

| 参数名 | 类型   | 描述                        | 示例                                        | 必填 | 默认值 |
| ------ | ------ | --------------------------- | ------------------------------------------- | ---- | ------ |
| key    | string | 用户申请的外部 api 请求 key | "your_api_key_here"                         | 是   |        |
| uri    | string | 接口路径                    | "/v3/api/open/ai-search/image/resultSummary" | 是   |        |
| params | object | 接口入参对象                | 见参数列表                                  | 是   |        |

### 请求体参数 (params 对象)

| 参数名   | 类型   | 必填 | 描述                                                                                                                                                                                                                                 |
| -------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| image_id | String | 是   | 图片唯一标识ID，通过图片提交接口（/v3/api/open/ai-search/image/submit 或 /v3/api/open/ai-search/image/submit/image-url）返回获得。格式：img_开头+时间戳                                                                            |

### 请求示例

#### 使用 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/resultSummary",
    "params": {
        "image_id": "img_1737532800123456"
    }
  }'
```

## 响应参数

### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "products": 156,
    "creatives": 89,
    "root_path": 45,
    "tiktok_shop_products": 78,
    "tiktok_shop_stores": 23
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

### 响应字段说明

| 字段名                      | 类型    | 描述                                                                 |
| --------------------------- | ------- | -------------------------------------------------------------------- |
| code                        | Integer | 响应状态码，200 表示成功                                             |
| message                     | String  | 响应消息                                                             |
| data                        | Object  | 响应数据                                                             |
| data.products               | Integer | 搜索到的相似产品数量（电商平台产品）                                 |
| data.creatives              | Integer | 搜索到的相似广告创意数量（包含该产品的广告视频/图片）                |
| data.root_path              | Integer | 搜索到的相关店铺数量（广告主/店铺）                                  |
| data.tiktok_shop_products   | Integer | 搜索到的TikTok小店产品数量                                           |
| data.tiktok_shop_stores     | Integer | 搜索到的TikTok小店店铺数量                                           |
| version                     | String  | API 版本                                                             |
| timestamp                   | String  | 响应时间戳                                                           |
| sign                        | String  | 响应签名                                                             |
| remaining_credits | Long    | 当前请求后的剩余可用积分 |
| consumed_credits  | Long    | 本次请求消耗的积分 |
| success                     | Boolean | 请求是否成功                                                         |
| fail                        | Boolean | 请求是否失败                                                         |

### 数据字段说明

| 字段名                | 说明                                                                 | 后续查询接口                                      |
| --------------------- | -------------------------------------------------------------------- | ------------------------------------------------- |
| products              | 普通电商平台的产品数量（如Shopify、WooCommerce等独立站产品）        | `/v3/api/open/ai-search/image/product/search`     |
| creatives             | 包含相似产品的广告创意数量（TikTok、Facebook等平台的广告）           | `/v3/api/open/ai-search/image/search4/ad/search`          |
| root_path             | 投放相关广告的店铺/广告主数量                                        | `/v3/api/open/ai-search/image/root-path/search`   |
| tiktok_shop_products  | TikTok小店中的相似产品数量                                           | `/v3/api/open/ai-search/image/tiktok-product/search` |
| tiktok_shop_stores    | 销售相似产品的TikTok小店店铺数量                                     | `/v3/api/open/ai-search/image/tiktok-shop/search` |

## 响应示例

### 成功响应

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "products": 156,
    "creatives": 89,
    "root_path": 45,
    "tiktok_shop_products": 78,
    "tiktok_shop_stores": 23
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

## 错误码说明

| 错误码 | 描述                                                       |
| ------ | ---------------------------------------------------------- |
| 200    | 成功                                                       |
| 400    | 请求参数错误（image_id缺失、图片记录不存在、处理未完成等） |
| 401    | 未授权（API Key无效或过期）                                |
| 500    | 服务器内部错误                                             |

## 调用时机

1. **图片提交后**：在调用图片提交接口后，等待10-20秒，先调用状态接口确认处理完成
2. **状态确认后**：确认图片处理状态为"已完成"后，调用此接口获取结果摘要
3. **详细查询前**：在调用具体的产品、广告、店铺列表接口前，先调用此接口了解数据概况

## 典型使用流程

```
1. 提交图片
   ↓
2. 等待10-20秒
   ↓
3. 查询处理状态（/v3/api/open/ai-search/image/status）
   ↓
4. 获取结果摘要（本接口）
   ↓
5. 根据摘要数据，选择性调用详细列表接口：
   - 产品列表：/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
```