# 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 Information - **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](https://www.pipispy.com/zh/doc/others-region) | | 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 ```bash 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 ```bash 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 ```bash 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 ```json { "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\ | 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\ | 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 | #### 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 ```json { "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 | --- ## Related APIs The complete image search TikTok 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**: `/v3/api/open/ai-search/image/product/search` 6. **Store Search**: `/v3/api/open/ai-search/image/root-path/search` 7. **TikTok Product Search** (This API): `/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. **Keyword Search**: Supports searching by product name, store name, influencer name, and other dimensions 3. **Region Filtering**: Supports filtering by product target region 4. **Sales Data**: Supports filtering by sales volume, GMV, sales trend, and other sales metrics 5. **Ad Data**: Supports filtering by ad play count, ad count, ad spend, and other ad metrics 6. **Delivery Method**: Supports filtering by cross-border or local shipping 7. **Time Range**: Use time parameter to get product data within specified time range 8. **Influencer Marketing**: Supports filtering by influencer count to understand product's influencer marketing situation