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-to-Ad Search API

Overall Calling Process

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 (This API)
    - Shop 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-to-Ad Search API is used to search for similar ad content based on an image. You need to first obtain an image_id through the image submission API, then use this API to query the ad list 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 ads.


API Information

  • API Name: Image-to-Ad Search
  • Request Method: POST
  • API Endpoint: /open-api/v1/data
  • API Path: /v3/api/open/ai-search/image/search4/ad/search
  • API Description: Query similar ads based on image ID, supporting 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 External API request key "your_api_key_here" Yes
uri string API path "/v3/api/open/ai-search/image/search4/ad/search" Yes
params object API input parameter object See parameter list Yes

Request Body Parameters (params object)

Required Parameters

Parameter Type Required Description
image_id String Yes Image ID obtained from 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, recommended range: 1-100

Optional Parameters - Platform and Data Type

Parameter Type Required Description
plat_type Integer No Platform type: 0-All, 1-TikTok, 2-Facebook. Default: 0
data_type List<Integer> No Data type list: 1-Product copying, 2-TikTok Shop (TTS) ads, 3-E-commerce, 4-Spark Ads, 5-Games, 6-Apps, 7-AI, 8-Short dramas

Optional Parameters - Region and Language

Parameter Type Required Description
region List<String> No Region list, supports GB/UK and other region codes, see Country Regions. When "other" is included, automatically expands to other regions
ad_language List<String> No Ad language list using ISO 639-1 standard language codes (2-letter lowercase). Example: ["en", "de"], supports "other" for other languages
in_china Boolean No Whether in mainland China. Default: false
Parameter Type Required Description
extend_keywords List<ExtendKeyWordsVo> No Extended keyword list, supports searching by different types. See ExtendKeyWordsVo structure
exclude_word List<ExcludeWordVo> No Exclude word list. See ExcludeWordVo structure
is_participle Boolean No Whether to use word segmentation. Default: true
is_and Boolean No Multi-word query logic, false-OR logic, true-AND logic. Default: false

ExtendKeyWordsVo Structure:

Field Type Required Description
keyword String Yes Keyword
type int Yes Search type:
1 - Ad keyword search, user's keyword will search ad copy, advertiser, landing page link, product, App, account, and creative
2 - Ad copy, user's keyword will only search ad copy
3 - Advertiser, user's keyword will search advertisers
4 - Landing page URL, user's keyword will search landing page links and redirect links
5 - E-commerce product, user's keyword will search e-commerce product names
6 - TikTok Shop, user's keyword will search TikTok Shop names
7 - APP name, user's keyword will search App names
8 - APP developer, user's keyword will search APP developer names
9 - Social media account (page name), user's keyword will search social media accounts (TT account/Page ID)
10 - Creative (script/hook/tag), user's keyword will search creative info (script/hook/tag)
11 - E-commerce shop/URL, user's keyword will search e-commerce shop/URL
12 - TikTok Shop product, user's keyword will search TikTok Shop products

ExcludeWordVo Structure:

Field Type Required Description
keyword String Yes Exclude keyword
type int Yes Exclude type, same values as ExtendKeyWordsVo

Optional Parameters - Shop and Product

Parameter Type Required Description
shop_type List<String> No Shop type list:
shopify
woocommerce
shoplazza
shopline
magento
cafe24
shopyy
prestashop
1c-bitrix
3dcart
bigcartel
bigcommerce
ecwid
miva
nuvemshop
squarespace
strikingly
tiendanube
ueeshop
volusion
wix
wordpress
root_path String No Root path
is_tiktok_shop Boolean No Whether it's a TikTok Shop
product_id String No Product ID
tk_shop_category_id List<String> No TikTok Shop category ID list
product_category_id List<String> No E-commerce category ID list, same as ad product page categories
Parameter Type Required Description
is_app Boolean No Whether it's an app ad
app_system String No App platform: ios/android, supports comma-separated multiple platforms
app_type String No App type
app_category List<String> No App category list
app_dev_id String No App developer ID
app_id String No App ID

Optional Parameters - Interaction Data Range

Parameter Type Required Description
play_count_min Long No Minimum play count
play_count_max Long No Maximum play count
digg_count_min Long No Minimum like count
digg_count_max Long No Maximum like count
comment_count_min Long No Minimum comment count
comment_count_max Long No Maximum comment count
share_count_min Long No Minimum share count
share_count_max Long No Maximum share count
download_count_min Long No Minimum download count
download_count_max Long No Maximum download count
hot_value_min Long No Minimum hot value (hot value = likes + comments + shares)
hot_value_max Long No Maximum hot value
digg_rate_min Double No Minimum like rate
digg_rate_max Double No Maximum like rate
share_play_rate_min Double No Minimum share-play rate
share_play_rate_max Double No Maximum share-play rate

Optional Parameters - Facebook Interaction Data

Parameter Type Required Description
reaction_wow_min Long No Facebook "Wow" reaction minimum
reaction_wow_max Long No Facebook "Wow" reaction maximum
reaction_love_min Long No Facebook "Love" reaction minimum
reaction_love_max Long No Facebook "Love" reaction maximum
reaction_haha_min Long No Facebook "Haha" reaction minimum
reaction_haha_max Long No Facebook "Haha" reaction maximum
reaction_sad_min Long No Facebook "Sad" reaction minimum
reaction_sad_max Long No Facebook "Sad" reaction maximum
reaction_anger_min Long No Facebook "Anger" reaction minimum
reaction_anger_max Long No Facebook "Anger" reaction maximum
reaction_care_min Long No Facebook "Care" reaction minimum
reaction_care_max Long No Facebook "Care" reaction maximum

Optional Parameters - Time Range

Parameter Type Required Description
create_time_start Long No Creation time start (Unix timestamp, seconds)
create_time_end Long No Creation time end (Unix timestamp, seconds)
first_time_start Long No First discovery time start (Unix timestamp, seconds)
first_time_end Long No First discovery time end (Unix timestamp, seconds)
last_time_start Long No Last modified time start (Unix timestamp, seconds)
last_time_end Long No Last modified time end (Unix timestamp, seconds)
put_day_min Long No Minimum number of days running
put_day_max Long No Maximum number of days running
release_time_start Long No APP release time start (Unix timestamp, seconds)
release_time_end Long No APP release time end (Unix timestamp, seconds)

Optional Parameters - Ad Properties

Parameter Type Required Description
formate_type List<Integer> No Ad format type list
button List<String> No Button type list
age List<String> No Age range list, format like "18-24"
sex List<Integer> No Gender list: 0-All, 1-Male, 2-Female
is_url Integer No URL status: 0-No landing page link, 1-Has landing page link
is_ad_fake Boolean No Whether it's a non-branded ad (not TikTok Spark Ads)
is_product Boolean No Whether it's a product ad
is_redirect Boolean No Whether it has redirect URL
ad_duration_min Long No Minimum ad duration (seconds)
ad_duration_max Long No Maximum ad duration (seconds)
size List<String> No Aspect ratio list: 1:1, 16:9, 4:3, 9:16, 21:9, 1:2, 3:4, 4:5, 2:1, 5:4
clarity List<String> No Quality list: SD, HD, Full HD, UHD/4K, 8K
aspect_ratio List<String> No Resolution list: 640×360, 360×640, 854×480, 480×854, 720×720, 1080×1080, etc.
ad_status String No Ad status: 0-Stopped, 1-Running, comma-separated
ad_state Integer No Ad state: 0-Stopped, 1-Running
is_real String No Whether real person: no-AI, yes-Real person, empty defaults to all

Optional Parameters - Ad Cost and Conversion

Parameter Type Required Description
ad_cost_min Double No Minimum ad spend
ad_cost_max Double No Maximum ad spend
estimated_conversion_min Double No Minimum estimated conversions
estimated_conversion_max Double No Maximum estimated conversions

Optional Parameters - APP Data

Parameter Type Required Description
monthly_install_min Long No Minimum monthly installs
monthly_install_max Long No Maximum monthly installs
monthly_income_min Double No Minimum monthly revenue
monthly_income_max Double No Maximum monthly revenue
score_min Double No Minimum app rating
score_max Double No Maximum app rating

Optional Parameters - AI Analysis and Classification

Parameter Type Required Description
ai_analysis_tags List<String> No AI analysis tag list, query using script analysis tags
ai_category List<String> No AI category list, using AI categories on Toolify (not used yet)
skits_category List<String> No Short drama category list (not used yet)
interest String No Interest tags

Optional Parameters - Others

Parameter Type Required Description
popular_person_id String No Influencer ID
exclude_history Integer No Whether to exclude browsing history: 1-Exclude
is_recommend Integer No Whether it's recommended content
sort Integer No Sort method:
13-Sort by image similarity
3-First discovery time
4-Ad plays
5-Days running
6-Interactions
7-Like rate
8-Share rate
9-Likes
10-Comments
11-Shares
12-Creation time
sort_type String No Sort type: desc-Descending, asc-Ascending
user_search_time Long No User search time (Unix timestamp, seconds)
after String[] No Cursor pagination parameter

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

Advanced Filter Example

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/search4/ad/search",
    "params": {
        "image_id": "img_1737532800123456",
        "current_page": 1,
        "page_size": 20,
        "plat_type": 1,
        "region": ["US", "GB"],
        "extend_keywords": [
            {
                "keyword": "fashion",
                "type": 2
            }
        ],
        "play_count_min": 10000,
        "sort": 3,
        "sort_type": "desc"
    }
  }'

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 Type Description
code Integer Response status code, 200 indicates success
message String Response message
data Object Response data, contains data (ad 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 was successful
fail Boolean Whether request failed
Ad Data Fields (data) - Alphabetical Order
Field Name Type Description
id string Video ID (use this field as id to access ad details)
video_id string Video ID (use this field as id to access ad details)
ad_create_time number Ad creation time (timestamp)
ai_analysis_human_presenter string AI analysis human presenter
ai_analysis_language string AI analysis language
ai_analysis_main_hook string AI analysis main hook
ai_analysis_script string AI analysis script
ai_analysis_tags array[string] AI analysis tag list
app_dev_id string App developer ID
app_image string App image URL
app_name string App name
app_title string App title
button_text string Button text
carousel array[object] Carousel list
comment_count number Comment count
cover string Cover image URL
data_type array[number] Data type list
desc string Ad description
digg_count number Like count
digg_play_rate number Like-play rate
duration number Duration (seconds)
facebook_link_angry number Facebook angry reaction count
facebook_link_care number Facebook care reaction count
facebook_link_haha number Facebook haha reaction count
facebook_link_love number Facebook love reaction count
facebook_link_sad number Facebook sad reaction count
facebook_link_wow number Facebook wow reaction count
fetch_region array[string] Fetch region list
found_time number Discovery time (timestamp)
had_ai_analysis boolean Whether AI analysis was performed
have_tiktok_shop boolean Whether has TikTok shop
hot_value number Hot value
image string Image URL
is_collection boolean Whether collected
is_download boolean Whether downloadable
last_put_time number Last run time (timestamp)
min_cpa number Minimum estimated conversion, automatically calculated by PIPIADS based on big data and target region common order CPA metrics (with margin of error)
min_cpm number Minimum ad spend, automatically calculated by PIPIADS based on big data and target region common CPM metrics (with margin of error)
modify_time number Modification time (timestamp)
pack_url string Package URL
platform number Platform type (1:Facebook, 2:Instagram, 3:TikTok)
play_count number Play count
put_days number Number of days running
root_path_id string Advertiser ID
search_by_image_tag boolean Whether searched by image tag
share_count number Share count
share_play_rate number Share-play rate
shop_type string Shop type
type number Ad type (1:Video, 2:Image)
video_url string Video URL
_score Number Search keyword score
Field Name Type Description
aspect_ratio string Aspect ratio
body string Body content
button_text string Button text
cta_text string CTA text
cover string Cover image URL
cover_could_storage string Cover cloud storage
dimensions_type number Dimension type
duration number Duration (seconds)
height number Height
image string Image URL
image_could_storage string Image cloud storage
link_description string Link description
link_url string Link URL
play_count number Play count
quality string Quality
resolution string Resolution
title string Title
type number Type
video_audio_user_preferred_language string Video audio user preferred language
video_url string Video URL
video_url_could_storage string Video URL cloud storage
width number Width
Pagination Fields (page)
Field Name Type Description
total_count number Total record count
page_count number Total page count
current_page number Current page
page_size number Page size
is_next boolean Has next page

Response Example

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [
      {
        "search_by_image_tag": true,
        "comment_count": 2,
        "app_dev_id": "",
        "digg_play_rate": 0.0067,
        "modify_time": 1752204344,
        "pack_url": "",
        "type": 1,
        "is_collection": false,
        "platform": 1,
        "duration": 59,
        "cover": "https://cdn-video.pipispy.com/cover_7f33700d982493b5a19b158a7068af93.jpg",
        "share_play_rate": 0.0007,
        "last_put_time": 1752204344,
        "root_path_id": "61f57e4d9a301ef93d53b88a",
        "put_days": 12,
        "app_title": "I don't believe it! Your hair is oilier than mine!! #amaxy #fyp",
        "fetch_region": ["MY"],
        "ad_create_time": 1745303145,
        "play_count": 47527,
        "share_count": 32,
        "app_name": "🇲🇾 Livestream hosts Regina & Fiona",
        "found_time": 1749614161,
        "ad_id": "1833892866239586",
        "hot_value": 352,
        "digg_count": 318,
        "is_download": false,
        "data_type": [3],
        "button_text": "Beli sekarang",
        "desc": "I don't believe it! Your hair is oilier than mine!! #amaxy #fyp",
        "video_id": "d9055376ae19819f4756",
        "app_image": "https://cdn-video.pipispy.com/avatar_0aa449789bac7929f216b33fde973196.jpg",
        "video_url": "https://cdn-video.pipispy.com/video_39551dc815f2501724d82a30c4a389c3.mp4",
        "ai_analysis_main_hook": "Is your hair this oily?",
        "ai_analysis_script": "Is your hair this oily? I'm doing this test for you guys—I made such a big sacrifice! Look at all this oil—wow! Ugh, I have to do this again?! Seriously, is your hair this oily? Let me tell you—I only washed it once! I wanted to see if this product really works to remove oil. If it doesn't, don't buy it—okay? Is that enough? Look at the lather—it's actually quite rich and creamy, and it smells amazing! A fresh, clean fragrance! If you have oily hair, just get the blue one—it's specially designed to control oil. Then, use a bit of their conditioner, applying it only to the ends of your hair. Feel how smooth it is? Oh my god! I put on so much oil, and I only washed it once—look! It's completely clean, with zero greasiness or that nasty rancid-oil smell. My hair feels super dry, fresh, and incredibly voluminous—exactly as they claimed! So if you have oily hair, I highly recommend you get this blue Amaxy set. It comes as a gift box containing two shampoos (each 400ml) and one conditioner (also 400ml) to make your hair silky smooth. And guess what? For just over 100 bucks, I'll throw in two extra travel-size shampoos (100ml each) plus twelve mini sachets (8ml each)—that's nearly 300ml free! You're getting almost a full bottle (400ml) as a bonus! Going once… going twice… If your hair gets super oily even after just one day without washing, click the link in the bottom-left corner of the video to order now! It really works—you're gonna love it!",
        "ai_analysis_tags": [
          "#shampoo",
          "#conditioner",
          "#haircare",
          "#oilyhair",
          "#amaxy",
          "#hairproduct",
          "#hair",
          "#beauty"
        ],
        "ai_analysis_language": "zh-cn",
        "ai_analysis_human_presenter": "yes",
        "had_ai_analysis": true,
        "min_cpm": 33.74,
        "min_cpa": 1.0,
        "unique_id": "hows.sis"
      }
    ],
    "page": {
      "total_count": 10000,
      "page_count": 500,
      "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-to-ad search process 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 (This API): /v3/api/open/ai-search/image/search4/ad/search
  5. Product Search: /v3/api/open/ai-search/image/product/search
  6. Shop 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