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
| 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/product/search" | Yes | |
| params | object | API input parameters | See parameter list | Yes |
Request Body Parameters (params object)
| Parameter | Type | Required | Description |
|---|---|---|---|
| image_id | String | Yes | Image ID, obtained through image submission API. Format: img_ prefix + timestamp |
| current_page | Integer | Yes | Current page number, starting from 1 |
| page_size | Integer | Yes | Number of items per page |
| plat_type | Integer | No | Platform type (0: All, 1: TikTok, 2: Facebook) |
| time | Integer | No | Time range (0: All, 1: Yesterday, 7: Last 7 days, 30: Last 30 days, 90: Last 90 days) |
| keyword | String | No | Search keyword |
| search_type | Integer | No | Search type (1: Product title, 2: Product description, 3: Advertiser URL, 4: Advertiser name, 5: Product keywords) |
| category | String | No | Product category ID list, see E-commerce Categories, use comma to separate multiple category IDs |
| region | String | No | Region list, supports region codes like GB/US, see Countries and Regions, use comma to separate multiple regions |
| play_count_min | Integer | No | Minimum ad play count |
| play_count_max | Integer | No | Maximum ad play count |
| digg_count_min | Integer | No | Minimum like count |
| digg_count_max | Integer | No | Maximum like count |
| digg_play_rate_min | Double | No | Minimum like rate |
| digg_play_rate_max | Double | No | Maximum like rate |
| comment_count_min | Integer | No | Minimum comment count |
| comment_count_max | Integer | No | Maximum comment count |
| share_count_min | Integer | No | Minimum share count |
| share_count_max | Integer | No | Maximum share count |
| video_count_min | Integer | No | Minimum ad count |
| video_count_max | Integer | No | Maximum ad count |
| put_day_min | Integer | No | Minimum days running |
| put_day_max | Integer | No | Maximum days running |
| create_time_start | Integer | No | Product creation time start value (Unix timestamp, seconds) |
| create_time_end | Integer | No | Product creation time end value (Unix timestamp, seconds) |
| tiktok_time_start | Integer | No | Ad start date, first discovery time start value (Unix timestamp, seconds); Note that this does not refer exclusively to the TikTok ad start time; the prefix “tiktok” is used merely as a naming convention and carries no actual distinguishing meaning. Specifically, when plat_type = 2, it refers to the Facebook ad start time; when plat_type = 0, it represents the start time of all ads collectively. |
| tiktok_time_end | Integer | No | Ad start date, first discovery time end value (Unix timestamp, seconds); Please note that this does not refer exclusively to the end value of the TikTok ad start time; the prefix "tiktok" is used solely as a naming convention and has no actual distinguishing meaning. Specifically, when plat_type = 2, it refers to the end value of the Facebook ad start time, and when plat_type = 0, it represents the end value of the start time for all ads collectively. |
| latest_found_time_start | Integer | No | Ad end date, latest discovery time start value (Unix timestamp, seconds) |
| latest_found_time_end | Integer | No | Ad end date, latest discovery time end value (Unix timestamp, seconds) |
| price_min | Double | No | Product price (USD), minimum price |
| price_max | Double | No | Product price (USD), maximum price |
| currency | String | No | Currency unit, use comma to separate multiple currencies |
| platform | String | No | Platform identifier, use comma to separate, supports: shopify, woocommerce, shoplazza, magento, wix, shopline, squarespace, shopyy |
| popular_person_count_min | Integer | No | Minimum influencer count (only valid when plat_type=1) |
| popular_person_count_max | Integer | No | Maximum influencer count (only valid when plat_type=1) |
| root_path | String | No | Advertiser name |
| id | String | No | Product ID, use comma to separate multiple IDs |
| store_id | String | No | Store unique identifier ID, 13-character string (e.g., c2d5b2547218a), corresponds to store_id field in store ranking list API response |
| after_id | String | No | Pagination cursor ID (for deep pagination) |
| after_key | String | No | Pagination cursor key (for deep pagination) |
| sort | Integer | No | Sort method: When plat_type=0 9-Sort by similarity (default) 0-Total start date 1-Total end date 2-Product creation time 3-Product price (USD) 4-Total ad count 5-Ad plays 6-Total likes 7-Days running When plat_type=1 9-Sort by similarity (default) 0-TikTok ad start time 1-TikTok ad end time 2-TikTok product creation time 3-TikTok product price (USD) 4-TikTok ad count 5-TikTok play count 6-TikTok like count 7-TikTok days running 8-TikTok influencer count When plat_type=2 9-Sort by similarity (default) 0-Facebook ad start time 1-Facebook ad end time 2-Facebook product creation time 3-Facebook product price (USD) 4-Facebook ad count 5-Facebook play count 6-Facebook like count 7-Facebook days running |
| sort_type | String | No | Sort type (asc: ascending, desc: descending) |
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
| Field Name | Type | Description |
|---|---|---|
| code | Integer | Response status code, 200 indicates success |
| message | String | Response message |
| data | Object | Response data, contains data (product list) and page (pagination info) |
| 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 |
Product Data Fields (data)
| Field Name | Type | Description |
|---|---|---|
| id | String | Product unique identifier ID |
| title | String | Product title |
| image | String | Product main image URL |
| price | Double | Product price |
| currency | String | Product price currency type |
| usd_price | Double | Product USD price |
| platform | String | Product platform identifier |
| is_collection | Boolean | Whether already collected |
| create_time | Long | Product creation timestamp |
| tiktok_time | Long | TikTok platform first discovery timestamp |
| found_time | Long | TikTok platform first discovery timestamp |
| latest_found_time | Long | TikTok platform latest discovery timestamp |
| play_count | Long | TikTok platform play count |
| digg_count | Long | TikTok platform like count |
| digg_play_rate | Double | TikTok platform like-to-play ratio |
| comment_count | Long | TikTok platform comment count |
| share_count | Long | TikTok platform share count |
| video_count | Long | TikTok platform video count |
| put_days | Long | TikTok platform days running |
| ad_platform_list | List<String> | Ad platform list (e.g., tiktok, facebook) |
| popular_person_count | Long | Influencer count |
| facebook_data_count | Long | Facebook platform data count |
| facebook_digg_count | Long | Facebook platform like count |
| facebook_found_time | Long | Facebook platform first discovery timestamp |
| facebook_latest_found_time | Long | Facebook platform latest discovery timestamp |
| facebook_put_days | Long | Facebook platform days running |
| facebook_share_count | Long | Facebook platform share count |
| facebook_comment_count | Long | Facebook platform comment count |
| all_data_count | Long | All platforms data count |
| all_digg_count | Long | All platforms like count |
| all_found_time | Long | All platforms first discovery timestamp |
| all_latest_found_time | Long | All platforms latest discovery timestamp |
| all_put_days | Long | All platforms days running |
| all_share_count | Long | All platforms share count |
| all_comment_count | Long | All platforms comment count |
| sort_id | String | Sort ID (for pagination sorting) |
Pagination Info Fields (page)
| Field Name | Type | Description |
|---|---|---|
| total_count | Long | Total record count |
| page_count | Long | Total page count |
| current_page | Long | Current page number |
| page_size | Long | Page size |
| is_next | Boolean | Whether has next 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
| Error Code | Description |
|---|---|
| 200 | Success |
| 400 | Request parameter error |
| 401 | Unauthorized - Invalid API key |
| 500 | Internal server error |
Related APIs
The complete image search product flow involves the following APIs:
- Image Submission:
/v3/api/open/ai-search/image/submitor/v3/api/open/ai-search/image/submit/image-url - Processing Status Query:
/v3/api/open/ai-search/image/status - Result Summary:
/v3/api/open/ai-search/image/resultSummary - Ad Search:
/v3/api/open/ai-search/image/search4/ad/search - Product Search (This API):
/v3/api/open/ai-search/image/product/search - Store Search:
/v3/api/open/ai-search/image/root-path/search - TikTok Product Search:
/v3/api/open/ai-search/image/tiktok-product/search - TikTok Shop Search:
/v3/api/open/ai-search/image/tiktok-shop/search
Usage Notes
- Similarity Sorting: By default (sort=9), product list is sorted by image similarity in descending order, with most similar products first
- Platform Filtering: Use plat_type parameter to filter product data from specific platforms
- Time Range: Use time parameter to get product data within specified time range
- Keyword Search: Supports multiple search types, can search by product title, description, store URL, and other dimensions
- Region Filtering: Supports multi-region filtering, use comma to separate multiple region codes
- Category Filtering: Supports filtering by product category, requires correct category ID
- Data Statistics: Response includes complete statistics for TikTok, Facebook, and all platforms