Image Search - TikTok 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)
↓
2. Wait 10-20 seconds
↓
3. Query processing status (/v3/api/open/ai-search/image/status)
↓
4. Get result summary (/v3/api/open/ai-search/image/resultSummary)
↓
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 (This API)
- TikTok shops: /v3/api/open/ai-search/image/tiktok-shop/search
API Overview
The Image Search TikTok Product API is used to search for similar TikTok Shop 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 TikTok products similar to the image.
This API supports rich filtering conditions, including keyword search, region, category, sales volume, price, ad data, and other multi-dimensional filtering to help users accurately locate target products.
- API Name: Image Search TikTok Product
- Request Method: POST
- API Address:
/open-api/v1/data
- API Path:
/v3/api/open/ai-search/image/tiktok-product/search
- API Description: Query similar TikTok 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/tiktok-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, default is 1 |
| page_size |
Integer |
Yes |
Number of items per page, default is 20 |
| search_type |
Integer |
No |
Search type (1: Search by product name (description), 2: Search by store name, 3: Search by influencer name). Default: 1 |
| keyword |
String |
No |
Search keyword, used with search_type |
| region |
String |
No |
Region, supports region codes like GB/US, see Countries and Regions |
| categorize |
String |
No |
Category ID |
| sales_volume_min |
Long |
No |
Minimum sales volume |
| sales_volume_max |
Long |
No |
Maximum sales volume |
| gmv_min |
Long |
No |
Minimum GMV (sales amount) |
| gmv_max |
Long |
No |
Maximum GMV (sales amount) |
| sales_trend |
Integer |
No |
Sales trend (1: Growing, 0: Stable, -1: Declining) |
| person_count_min |
Integer |
No |
Minimum influencer count |
| person_count_max |
Integer |
No |
Maximum influencer count |
| price_usd_min |
Integer |
No |
Minimum price (USD) |
| price_usd_max |
Integer |
No |
Maximum price (USD) |
| delivery |
String |
No |
Delivery method (overseas: Cross-border shipping, local: Local shipping) |
| play_count_min |
Long |
No |
Minimum ad play count (ad impressions) |
| play_count_max |
Long |
No |
Maximum ad play count (ad impressions) |
| cpm_min |
Integer |
No |
Minimum ad spend |
| cpm_max |
Integer |
No |
Maximum ad spend |
| video_count_min |
Long |
No |
Minimum ad count |
| video_count_max |
Long |
No |
Maximum ad count |
| found_time_start |
Long |
No |
First ad discovery time start (Unix timestamp, seconds) |
| found_time_end |
Long |
No |
First ad discovery time end (Unix timestamp, seconds) |
| last_found_time_start |
Long |
No |
Last ad time start (Unix timestamp, seconds) |
| last_found_time_end |
Long |
No |
Last ad time end (Unix timestamp, seconds) |
| time |
Integer |
No |
Time range (0: All, 1: Yesterday, 7: Last 7 days, 30: Last 30 days, 90: Last 90 days). Default: 0 |
| sort |
Integer |
No |
Sort method (1: Last time, 2: Start time, 3: Sales volume, 4: GMV, 5: Ad play count, 6: Ad spend, 7: Ad count, 8: Influencer count, 9: Sort by similarity (default)) |
| sort_type |
String |
No |
Sort type (desc: Descending, asc: Ascending) |
| is_in_marketplace |
Boolean |
No |
Whether affiliate product, optional true/false |
| commission_rate |
Double |
No |
Commission rate, value between 0-1 |
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/tiktok-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/tiktok-product/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20,
"search_type": 1,
"keyword": "fashion",
"region": "US",
"sales_volume_min": 1000,
"price_usd_min": 10,
"price_usd_max": 100,
"sort": 3,
"sort_type": "desc"
}
}'
Filtering by Sales Trend and Delivery Method
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/tiktok-product/search",
"params": {
"image_id": "img_1737532800123456",
"current_page": 1,
"page_size": 20,
"sales_trend": 1,
"delivery": "overseas",
"gmv_min": 10000,
"time": 30,
"sort": 4
}
}'
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 |
| image |
String |
Product main image URL |
| title |
String |
Product title |
| desc |
String |
Product description |
| price |
Double |
Product price (local currency) |
| price_usd |
Double |
Product USD price |
| sales_volume |
Long |
Product sales volume |
| score |
Double |
Product rating |
| shop_name |
String |
Store name |
| shop_id |
String |
Store ID |
| shop_image |
String |
Store image URL |
| shop_sales_volume |
Long |
Store sales volume |
| video_count |
Long |
Ad video count |
| categorize |
CategoryDTO |
Product category info, see CategoryDTO object description below |
| region |
String |
Product target region |
| play_count |
Long |
Play count/ad impressions |
| share_count |
Long |
Share count |
| found_time |
Long |
First discovery time (timestamp, seconds) |
| last_found_time |
Long |
Last discovery time (timestamp, seconds) |
| insert_time |
Long |
Data insertion time (timestamp, seconds) |
| update_time |
Long |
Data update time (timestamp, seconds) |
| min_cpm |
Double |
Minimum ad spend (CPM) |
| max_cpm |
Double |
Maximum ad spend (CPM) |
| currency |
String |
Currency type |
| is_collection |
Boolean |
Whether already collected |
| root_path |
String |
Product root path (domain) |
| keywords |
List<String> |
Product keyword list |
| card_found_time |
Long |
Card first discovery time (timestamp, seconds) |
| card_last_found_time |
Long |
Card last discovery time (timestamp, seconds) |
| commission_rate |
Double |
Commission rate, value between 0-1 |
| sales_trend |
Integer |
Sales trend (1: Growing, 0: Stable, -1: Declining) |
| sales_trend_data |
List<SalesTrendData> |
Sales trend data list, see SalesTrendData object description below |
| gmv |
Double |
Sales amount (GMV) |
| gmv_usd |
Double |
USD sales amount (GMV USD) |
| delivery |
String |
Delivery method (overseas: Cross-border, local: Local) |
| is_in_marketplace |
Boolean |
Whether affiliate product, optional true/false |
| is_managed |
Boolean |
Whether fully managed product |
| person_count |
Long |
Influencer count |
CategoryDTO Object Info
| Field Name |
Type |
Description |
| _id |
String |
Category ID |
| name_zh |
String |
Chinese name |
| name_vi |
String |
Vietnamese name |
| name_th |
String |
Thai name |
| name_pt |
String |
Portuguese name |
| name_ja |
String |
Japanese name |
| name_id |
String |
Indonesian name |
| name_en |
String |
English name |
SalesTrendData Object Info
| Field Name |
Type |
Description |
| day |
Long |
Statistics time (timestamp, seconds) |
| sales_volume |
Long |
Sales volume |
| 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",
"image": "https://cdn-product.pipispy.com/tiktok_product_001.jpg",
"title": "Wireless Bluetooth Earbuds",
"desc": "High quality wireless earbuds with noise cancellation",
"price": 29.99,
"price_usd": 29.99,
"sales_volume": 15234,
"score": 4.8,
"shop_name": "TechStore Official",
"shop_id": "shop_12345",
"shop_image": "https://cdn-shop.pipispy.com/shop_icon.jpg",
"shop_sales_volume": 125000,
"video_count": 45,
"categorize": {
"id": "cat_001",
"name": "Electronics"
},
"region": "US",
"play_count": 2345678,
"share_count": 12345,
"found_time": 1700000000,
"last_found_time": 1737532800,
"insert_time": 1700000000,
"update_time": 1737532800,
"min_cpm": 15.5,
"max_cpm": 45.8,
"currency": "USD",
"is_collection": false,
"root_path": "tiktok.com",
"keywords": ["wireless", "bluetooth", "earbuds"],
"card_found_time": 1700086400,
"card_last_found_time": 1737446400,
"commission_rate": 0.15,
"sales_trend": 1,
"sales_trend_data": [],
"gmv": 456789.50,
"gmv_usd": 456789.50,
"delivery": "overseas",
"is_in_marketplace": true,
"is_managed": false,
"person_count": 23
},
{
"id": "product_002",
"image": "https://cdn-product.pipispy.com/tiktok_product_002.jpg",
"title": "Smart Watch Fitness Tracker",
"desc": "Advanced fitness tracker with heart rate monitor",
"price": 49.99,
"price_usd": 49.99,
"sales_volume": 8765,
"score": 4.6,
"shop_name": "FitGear Store",
"shop_id": "shop_67890",
"shop_image": "https://cdn-shop.pipispy.com/shop_icon2.jpg",
"shop_sales_volume": 89000,
"video_count": 32,
"categorize": {
"id": "cat_002",
"name": "Wearables"
},
"region": "GB",
"play_count": 1234567,
"share_count": 8901,
"found_time": 1699913600,
"last_found_time": 1737446400,
"insert_time": 1699913600,
"update_time": 1737446400,
"min_cpm": 18.2,
"max_cpm": 52.3,
"currency": "USD",
"is_collection": true,
"root_path": "tiktok.com",
"keywords": ["smartwatch", "fitness", "tracker"],
"card_found_time": 1700000000,
"card_last_found_time": 1737360000,
"commission_rate": 0.12,
"sales_trend": 0,
"sales_trend_data": [],
"gmv": 437823.35,
"gmv_usd": 437823.35,
"delivery": "local",
"is_in_marketplace": true,
"is_managed": true,
"person_count": 18
}
],
"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 |
The complete image search TikTok product flow involves the following APIs:
- Image Submission:
/v3/api/open/ai-search/image/submit or /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:
/v3/api/open/ai-search/image/product/search
- Store Search:
/v3/api/open/ai-search/image/root-path/search
- TikTok Product Search (This API):
/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
- Keyword Search: Supports searching by product name, store name, influencer name, and other dimensions
- Region Filtering: Supports filtering by product target region
- Sales Data: Supports filtering by sales volume, GMV, sales trend, and other sales metrics
- Ad Data: Supports filtering by ad play count, ad count, ad spend, and other ad metrics
- Delivery Method: Supports filtering by cross-border or local shipping
- Time Range: Use time parameter to get product data within specified time range
- Influencer Marketing: Supports filtering by influencer count to understand product's influencer marketing situation