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

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",
        "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:

  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