# 以图搜同款状态查询接口
## 调用整体流程
```
1. 提交图片 （/v3/api/open/ai-search/image/submit或/v3/api/open/ai-search/image/submit/image-url）
   ↓
2. 等待10-20秒
   ↓
3. 查询处理状态（/v3/api/open/ai-search/image/status）（本接口）
   ↓
4. 获取结果摘要（/v3/api/open/ai-search/image/resultSummary）
   ↓
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
```
## 接口信息

- **接口名称**: 查询图片处理状态
- **请求方法**: GET
- **接口地址**: `/open-api/v1/data`
- **接口路径**: `/v3/api/open/ai-search/image/status`
- **接口描述**: 查询图片处理的当前状态，用于判断图片是否处理完成。建议在图片提交后定期轮询此接口，直到状态变为 SEARCH_COMPLETED
- **价格说明**: 免费

**请求头:**

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

## 请求参数

### 请求结构

| 参数名 | 类型   | 描述                        | 示例                                 | 必填 | 默认值 |
| ------ | ------ | --------------------------- | ------------------------------------ | ---- | ------ |
| key    | string | 用户申请的外部 api 请求 key | "your_api_key_here"                  | 是   |        |
| uri    | string | 接口路径                    | "/v3/api/open/ai-search/image/status" | 是   |        |
| 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/status",
    "params": {
        "image_id": "img_1737532800123456"
    }
  }'
```

## 响应参数

### 响应体结构

```json
{
  "code": 200,
  "message": "success",
  "data": "SEARCH_COMPLETED",
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 0,
  "success": true,
  "fail": false
}
```

### 响应字段说明

| 字段名    | 类型    | 描述                                                                 |
| --------- | ------- | -------------------------------------------------------------------- |
| code      | Integer | 响应状态码，200 表示成功                                             |
| message   | String  | 响应消息                                                             |
| data      | String  | 图片处理状态，见状态值说明                                           |
| version   | String  | API 版本                                                             |
| timestamp | String  | 响应时间戳                                                           |
| sign      | String  | 响应签名                                                             |
| remaining_credits | Long    | 当前请求后的剩余可用积分 |
| consumed_credits  | Long    | 本次请求消耗的积分 |
| success   | Boolean | 请求是否成功                                                         |
| fail      | Boolean | 请求是否失败                                                         |

### 状态值说明

| 状态值              | 说明                                                                 | 是否可查询结果 | 建议操作                                           |
| ------------------- | -------------------------------------------------------------------- | -------------- | -------------------------------------------------- |
| UPLOAD_COMPLETED    | 图片上传完成，正在进行向量提取                                       | 否             | 继续轮询，等待向量提取完成                         |
| ANALYSIS_COMPLETED  | 向量提取完成，正在进行向量检索                                       | 否             | 继续轮询，等待检索完成                             |
| SEARCH_COMPLETED    | 搜索完成，所有处理已完成                                             | 是             | 可以调用结果摘要和详细列表接口获取搜索结果         |
| ANALYSIS_FAILURE    | 向量提取失败                                                         | 否             | 可能是图片内容无法识别，尝试更换图片               |
| SEARCH_FAILURE      | 向量检索失败                                                         | 否             | 系统错误，请联系技术支持                           |

## 响应示例

### 处理完成

```json
{
  "code": 200,
  "message": "success",
  "data": "SEARCH_COMPLETED",
  "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. **轮询图片处理进度**：在用户提交图片后，定期查询处理状态，实时展示处理进度
2. **判断是否可查询结果**：确认状态为 SEARCH_COMPLETED 后，再调用结果摘要和详细列表接口
3. **错误处理**：及时发现处理失败，给用户相应提示
4. **用户体验优化**：在UI上展示处理进度条或状态提示

## 典型使用流程

```
1. 提交图片
   ↓
2. 等待3-5秒后开始轮询状态
   ↓
3. 调用状态接口
   ├─ 如果状态为 UPLOAD_COMPLETED/ANALYSIS_COMPLETED
   │  └─ 等待2-3秒后继续轮询
   ├─ 如果状态为 SEARCH_COMPLETED
   │  └─ 进入步骤4
   └─ 如果状态为 *_FAILURE
      └─ 处理失败，检查错误原因
   ↓
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
```