Pipispy API中文

Data usage rules: 1. Obtaining a data result consumes 1 data. Obtaining more detailed information about a data result does not consume data. 2. Ad Tracker: Each monitoring session costs $1/month. Each monitoring session is valid for one month and automatically expires after one month. Deleting a monitoring session does not restore the monitoring session, so please delete with caution. Monitoring sessions can be accessed at any time and are unlimited.

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

  1. After Image Submission: After calling image submission API, wait 10-20 seconds, first call status API to confirm processing is complete
  2. After Status Confirmation: After confirming image processing status is "completed", call this API to get result summary
  3. 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