Image Search - Result Summary API
Overall Call Flow
1. Submit image (/v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url), get image_id
↓
2. Wait 10-20 seconds
↓
3. Query processing status based on image_id (/v3/api/open/ai-search/image/status)
↓
4. Get result summary based on image_id (/v3/api/open/ai-search/image/resultSummary) (This API)
↓
5. Based on summary data and image_id, 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: Get Image Search Result Summary
- Request Method: GET
- API Address:
/open-api/v1/data
- API Path:
/v3/api/open/ai-search/image/resultSummary
- API Description: Get statistical summary information of image search results, including counts of products, ads, stores, and other data types found. Must first call image submission API to get image_id, and wait for image processing to complete before calling this API
- 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/resultSummary" |
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/resultSummary",
"params": {
"image_id": "img_1737532800123456"
}
}'
Response Parameters
Response Body Structure
{
"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
}
Response Field Description
| Field Name |
Type |
Description |
| code |
Integer |
Response status code, 200 indicates success |
| message |
String |
Response message |
| data |
Object |
Response data |
| data.products |
Integer |
Number of similar products found (e-commerce platform products) |
| data.creatives |
Integer |
Number of similar ad creatives found (ad videos/images containing the product) |
| data.root_path |
Integer |
Number of related stores found (advertisers/stores) |
| data.tiktok_shop_products |
Integer |
Number of TikTok Shop products found |
| data.tiktok_shop_stores |
Integer |
Number of TikTok Shop stores found |
| 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 |
Data Field Description
| Field Name |
Description |
Subsequent Query API |
| products |
Number of regular e-commerce platform products (such as Shopify, WooCommerce independent site products) |
/v3/api/open/ai-search/image/product/search |
| creatives |
Number of ad creatives containing similar products (ads from TikTok, Facebook, etc.) |
/v3/api/open/ai-search/image/search4/ad/search |
| root_path |
Number of stores/advertisers running related ads |
/v3/api/open/ai-search/image/root-path/search |
| tiktok_shop_products |
Number of similar products in TikTok Shop |
/v3/api/open/ai-search/image/tiktok-product/search |
| tiktok_shop_stores |
Number of TikTok Shop stores selling similar products |
/v3/api/open/ai-search/image/tiktok-shop/search |
Response Examples
Success Response
{
"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
}
Error Code Description
| Error Code |
Description |
| 200 |
Success |
| 400 |
Request parameter error (missing image_id, image record not found, processing not complete, etc.) |
| 401 |
Unauthorized (invalid or expired API Key) |
| 500 |
Internal server error |
Call Timing
- After Image Submission: After calling image submission API, wait 10-20 seconds, first call status API to confirm processing is complete
- After Status Confirmation: After confirming image processing status is "completed", call this API to get result summary
- Before Detailed Query: Before calling specific product, ad, store list APIs, first call this API to understand data overview
Typical Usage Flow
1. Submit image
↓
2. Wait 10-20 seconds
↓
3. Query processing status (/v3/api/open/ai-search/image/status)
↓
4. Get result summary (This API)
↓
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