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 Information

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
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