# Image Search - Status Query API
## Overall Call Flow
```
1. Submit image (/v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url)
   ↓
2. Wait 10-20 seconds
   ↓
3. Query processing status (/v3/api/open/ai-search/image/status) (This API)
   ↓
4. Get result summary (/v3/api/open/ai-search/image/resultSummary)
   ↓
5. Based on summary data, selectively call detailed list APIs:
    - Product list: /v3/api/open/ai-search/image/product/search
    - Ad list: /v3/api/open/ai-search/image/search4/ad/search
    - Store list: /v3/api/open/ai-search/image/root-path/search
    - TikTok products: /v3/api/open/ai-search/image/tiktok-product/search
    - TikTok shops: /v3/api/open/ai-search/image/tiktok-shop/search
```
## API Information

- **API Name**: Query Image Processing Status
- **Request Method**: GET
- **API Address**: `/open-api/v1/data`
- **API Path**: `/v3/api/open/ai-search/image/status`
- **API Description**: Query the current processing status of an image to determine if processing is complete. It's recommended to poll this API periodically after image submission until the status becomes SEARCH_COMPLETED
- **Pricing**: Free

**Request Headers:**

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

## Request Parameters

### Request Structure

| Parameter | Type   | Description                 | Example                                | Required | Default |
| --------- | ------ | --------------------------- | -------------------------------------- | -------- | ------- |
| key       | string | User's external API request key | "your_api_key_here"                    | Yes      |         |
| uri       | string | API path                    | "/v3/api/open/ai-search/image/status" | Yes      |         |
| params    | object | API input parameters        | See parameter list                     | Yes      |         |

### Request Body Parameters (params object)

| Parameter | Type   | Required | Description                                                                                                                                                                                                                          |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| image_id  | String | Yes      | Image unique identifier ID, obtained from image submission API (/v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url). Format: img_ prefix + timestamp                                            |

### Request Examples

#### Using 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"
    }
  }'
```

## Response Parameters

### Response Body Structure

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

### Response Field Description

| Field Name | Type    | Description                                  |
| ---------- | ------- | -------------------------------------------- |
| code       | Integer | Response status code, 200 indicates success  |
| message    | String  | Response message                             |
| data       | String  | Image processing status, see status values   |
| version    | String  | API version                                  |
| timestamp  | String  | Response timestamp                           |
| sign       | String  | Response signature                           |
| remaining_credits | Long    | Current remaining available credits after this request |
| consumed_credits  | Long    | Credits consumed by this request                       |
| success    | Boolean | Whether request succeeded                    |
| fail       | Boolean | Whether request failed                       |

### Status Value Description

| Status Value        | Description                                                          | Can Query Results | Recommended Action                                 |
| ------------------- | -------------------------------------------------------------------- | ----------------- | -------------------------------------------------- |
| UPLOAD_COMPLETED    | Image upload complete, vector extraction in progress                 | No                | Continue polling, wait for vector extraction       |
| ANALYSIS_COMPLETED  | Vector extraction complete, vector retrieval in progress             | No                | Continue polling, wait for retrieval completion    |
| SEARCH_COMPLETED    | Search complete, all processing finished                             | Yes               | Can call result summary and detailed list APIs     |
| ANALYSIS_FAILURE    | Vector extraction failed                                             | No                | Image content may be unrecognizable, try another   |
| SEARCH_FAILURE      | Vector retrieval failed                                              | No                | System error, please contact technical support     |

## Response Examples

### Processing Complete

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


## Error Code Description

| Error Code | Description                                                       |
| ---------- | ----------------------------------------------------------------- |
| 200        | Success                                                           |
| 400        | Request parameter error (missing image_id, image record not found, etc.) |
| 401        | Unauthorized (invalid or expired API Key)                         |
| 500        | Internal server error                                             |

## Use Cases

This API is mainly used for the following scenarios:

1. **Poll Image Processing Progress**: After user submits image, periodically query processing status to display real-time progress
2. **Determine if Results Can Be Queried**: After confirming status is SEARCH_COMPLETED, call result summary and detailed list APIs
3. **Error Handling**: Promptly detect processing failures and provide appropriate user prompts
4. **User Experience Optimization**: Display progress bar or status prompts in UI

## Typical Usage Flow

```
1. Submit image
   ↓
2. Wait 3-5 seconds before starting to poll status
   ↓
3. Call status API
   ├─ If status is UPLOAD_COMPLETED/ANALYSIS_COMPLETED
   │  └─ Wait 2-3 seconds and continue polling
   ├─ If status is SEARCH_COMPLETED
   │  └─ Proceed to step 4
   └─ If status is *_FAILURE
      └─ Handle failure, check error reason
   ↓
4. Call result summary API to get search result statistics
   ↓
5. Call detailed list APIs as needed:
   - Product list: /v3/api/open/ai-search/image/product/search
   - Ad list: /v3/api/open/ai-search/image/search4/ad/search
   - Store list: /v3/api/open/ai-search/image/root-path/search
   - TikTok products: /v3/api/open/ai-search/image/tiktok-product/search
   - TikTok shops: /v3/api/open/ai-search/image/tiktok-shop/search
```