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 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
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
{
"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
{
"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:
- Poll Image Processing Progress: After user submits image, periodically query processing status to display real-time progress
- Determine if Results Can Be Queried: After confirming status is SEARCH_COMPLETED, call result summary and detailed list APIs
- Error Handling: Promptly detect processing failures and provide appropriate user prompts
- 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