Image Search - Product Search 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)
   ↓
5. Based on summary data and image_id, selectively call detailed list APIs:
    - Product list: /v3/api/open/ai-search/image/product/search (This API)
    - 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 Overview

The Image Search Product API is used to search for similar e-commerce products based on images. You need to first obtain an image_id through the image submission API, then use this API to query a list of products similar to the image.

This API supports rich filtering conditions, including platform type, data type, region, keywords, interaction data range, time range, and other multi-dimensional filtering to help users accurately locate target products.

API Information

• API Name: Image Search Product
• Request Method: POST
• API Address: /open-api/v1/data
• API Path: /v3/api/open/ai-search/image/product/search
• API Description: Query similar products based on image ID, supports multi-dimensional filtering and sorting
• Pricing: Retrieving one data result consumes 1 credit

Request Headers:

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

Request Parameters

Request Structure

Request Body Parameters (params object)

Request Examples

Basic Request Example

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/product/search",
    "params": {
        "image_id": "img_1737532800123456",
        "current_page": 1,
        "page_size": 20
    }
  }'

Advanced Filtering Examples

Using Keywords and Region Filtering

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/product/search",
    "params": {
        "image_id": "img_1737532800123456",
        "current_page": 1,
        "page_size": 20,
        "plat_type": 1,
        "region": "US,GB",
        "keyword": "fashion",
        "search_type": 2,
        "play_count_min": 10000,
        "sort": 0,
        "sort_type": "desc"
    }
  }'

Filtering by Price Range and Category

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/product/search",
    "params": {
        "image_id": "img_1737532800123456",
        "current_page": 1,
        "page_size": 20,
        "price_min": 10,
        "price_max": 100,
        "category": "62739afc38365b2f72048ebe",
        "time": 30,
        "sort": 9
    }
  }'

Response Parameters

Response Body Structure

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [ ... ],
    "page": { ... }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

Response Field Description

Top-level Fields

Product Data Fields (data)

Pagination Info Fields (page)

Response Examples

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "id": "product_001",
        "title": "Wireless Bluetooth Headphones",
        "image": "https://cdn-product.pipispy.com/product_001.jpg",
        "price": 29.99,
        "currency": "USD",
        "usd_price": 29.99,
        "platform": "shopify",
        "is_collection": false,
        "create_time": 1700000000,
        "tiktok_time": 1700086400,
        "found_time": 1700086400,
        "latest_found_time": 1737532800,
        "play_count": 1523456,
        "digg_count": 45678,
        "digg_play_rate": 0.03,
        "comment_count": 3456,
        "share_count": 1234,
        "video_count": 125,
        "put_days": 45,
        "ad_platform_list": ["tiktok", "facebook"],
        "popular_person_count": 23,
        "facebook_data_count": 56,
        "facebook_digg_count": 12345,
        "facebook_found_time": 1700172800,
        "facebook_latest_found_time": 1737446400,
        "facebook_put_days": 38,
        "facebook_share_count": 567,
        "facebook_comment_count": 890,
        "all_data_count": 181,
        "all_digg_count": 58023,
        "all_found_time": 1700086400,
        "all_latest_found_time": 1737532800,
        "all_put_days": 45,
        "all_share_count": 1801,
        "all_comment_count": 4346,
        "sort_id": "product_001"
      },
      {
        "id": "product_002",
        "title": "Smart Watch Fitness Tracker",
        "image": "https://cdn-product.pipispy.com/product_002.jpg",
        "price": 49.99,
        "currency": "USD",
        "usd_price": 49.99,
        "platform": "shopify",
        "is_collection": true,
        "create_time": 1699913600,
        "tiktok_time": 1700000000,
        "found_time": 1700000000,
        "latest_found_time": 1737446400,
        "play_count": 2345678,
        "digg_count": 78901,
        "digg_play_rate": 0.034,
        "comment_count": 5678,
        "share_count": 2345,
        "video_count": 198,
        "put_days": 52,
        "ad_platform_list": ["tiktok"],
        "popular_person_count": 45,
        "facebook_data_count": 0,
        "facebook_digg_count": 0,
        "facebook_found_time": 0,
        "facebook_latest_found_time": 0,
        "facebook_put_days": 0,
        "facebook_share_count": 0,
        "facebook_comment_count": 0,
        "all_data_count": 198,
        "all_digg_count": 78901,
        "all_found_time": 1700000000,
        "all_latest_found_time": 1737446400,
        "all_put_days": 52,
        "all_share_count": 2345,
        "all_comment_count": 5678,
        "sort_id": "product_002"
      }
    ],
    "page": {
      "total_count": 1000,
      "page_count": 50,
      "current_page": 1,
      "page_size": 20,
      "is_next": true
    }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

Error Code Description

Related APIs

The complete image search product flow involves the following APIs:

1. Image Submission: /v3/api/open/ai-search/image/submit or /v3/api/open/ai-search/image/submit/image-url
2. Processing Status Query: /v3/api/open/ai-search/image/status
3. Result Summary: /v3/api/open/ai-search/image/resultSummary
4. Ad Search: /v3/api/open/ai-search/image/search4/ad/search
5. Product Search (This API): /v3/api/open/ai-search/image/product/search
6. Store Search: /v3/api/open/ai-search/image/root-path/search
7. TikTok Product Search: /v3/api/open/ai-search/image/tiktok-product/search
8. TikTok Shop Search: /v3/api/open/ai-search/image/tiktok-shop/search

Usage Notes

1. Similarity Sorting: By default (sort=9), product list is sorted by image similarity in descending order, with most similar products first
2. Platform Filtering: Use plat_type parameter to filter product data from specific platforms
3. Time Range: Use time parameter to get product data within specified time range
4. Keyword Search: Supports multiple search types, can search by product title, description, store URL, and other dimensions
5. Region Filtering: Supports multi-region filtering, use comma to separate multiple region codes
6. Category Filtering: Supports filtering by product category, requires correct category ID
7. Data Statistics: Response includes complete statistics for TikTok, Facebook, and all platforms