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

Request Body Parameters (params object)

Required Parameters

Optional Parameters - Platform and Data Type

Optional Parameters - Region and Language

Optional Parameters - Keyword Search

ExtendKeyWordsVo Structure:

ExcludeWordVo Structure:

Optional Parameters - Shop and Product

Optional Parameters - APP Related

Optional Parameters - Interaction Data Range

Optional Parameters - Facebook Interaction Data

Optional Parameters - Time Range

Optional Parameters - Ad Properties

Optional Parameters - Ad Cost and Conversion

Optional Parameters - APP Data

Optional Parameters - AI Analysis and Classification

Optional Parameters - Others

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

Ad Data Fields (data) - Alphabetical Order

Carousel Fields (carousel) - Alphabetical Order

Pagination Fields (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

Related APIs

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