Pipispy APIEnglish

数据消耗规则:1. 获取一条数据结果消耗1 数据,获取数据结果的更多数据详情不消耗数据。2. 广告监控: 每次监控 $1 / 月。单个监控有效期为一个月,一个月后自动停止。删除监控不会恢复监控次数,请谨慎删除。监控调用为随时且无限次。

以图搜广告接口

调用整体流程

1. 提交图片 (/v3/api/open/ai-search/image/submit或/v3/api/open/ai-search/image/submit/image-url)
   ↓
2. 等待10-20秒
   ↓
3. 查询处理状态(/v3/api/open/ai-search/image/status)
   ↓
4. 获取结果摘要(/v3/api/open/ai-search/image/resultSummary)
   ↓
5. 根据摘要数据,选择性调用详细列表接口:
    - 产品列表:/v3/api/open/ai-search/image/product/search
    - 广告列表:/v3/api/open/ai-search/image/search4/ad/search (本接口)
    - 店铺列表:/v3/api/open/ai-search/image/root-path/search
    - TikTok产品:/v3/api/open/ai-search/image/tiktok-product/search
    - TikTok店铺:/v3/api/open/ai-search/image/tiktok-shop/search

接口概述

以图搜广告接口用于根据图片搜索相似的广告内容。需要先通过图片提交接口获取 image_id,然后使用该接口查询与图片相似的广告列表。

该接口支持丰富的过滤条件,包括平台类型、数据类型、地区、关键词、互动数据范围、时间范围等多维度筛选,帮助用户精准定位目标广告。


接口信息

  • 接口名称: 以图搜广告
  • 请求方法: POST
  • 接口地址: /open-api/v1/data
  • 接口路径: /v3/api/open/ai-search/image/search4/ad/search
  • 接口描述: 根据图片ID查询相似广告,支持多维度过滤和排序
  • 价格说明: 获取一条数据结果消耗1 credit

请求头:

  • Content-Type: application/json
  • Accept: application/json

请求参数

请求结构

参数名 类型 描述 示例 必填 默认值
key string 用户申请的外部 api 请求 key "your_api_key_here" 是
uri string 接口路径 "/v3/api/open/ai-search/image/search4/ad/search" 是
params object 接口入参对象 见参数列表 是

请求体参数 (params 对象)

必填参数

参数名 类型 必填 描述
image_id String 是 图片ID,通过图片提交接口获得。格式:img_开头+时间戳
current_page Integer 是 当前页码,从1开始
page_size Integer 是 每页数量,建议范围:1-100

可选参数 - 平台与数据类型

参数名 类型 必填 描述
plat_type Integer 否 平台类型:0-全部,1-TikTok,2-Facebook。默认:0
data_type List<Integer> 否 数据类型列表:1-爆品跟卖,2-小店(TTS)广告,3-电商,4-Spark Ads,5-游戏,6-App,7-AI,8-短剧

可选参数 - 地区与语言

参数名 类型 必填 描述
region List<String> 否 地区列表,支持GB/UK等地区代码,见 国家地区 包含"other"时自动扩展其他地区
ad_language List<String> 否 广告语言列表,使用ISO 639-1标准的语言代码(2位小写字母)。示例:["en", "de"],支持"other"表示其他语言
in_china Boolean 否 是否在中国境内。默认:false

可选参数 - 关键词搜索

参数名 类型 必填 描述
extend_keywords List<ExtendKeyWordsVo> 否 扩展关键词列表,支持按不同类型搜索。详见 ExtendKeyWordsVo 结构
exclude_word List<ExcludeWordVo> 否 排除词汇列表。详见 ExcludeWordVo 结构
is_participle Boolean 否 是否分词。默认:true
is_and Boolean 否 多词查询逻辑,false-OR逻辑,true-AND逻辑。默认:false

ExtendKeyWordsVo 结构:

字段名 类型 必填 描述
keyword String 是 关键词
type int 是 搜索类型:
1 - 广告关键词搜索,用户输入的keyword 将会进行广告文案、广告主、落地页链接、产品、App、账号、素材匹配搜索
2 - 广告文案,用户输入的keyword 只会进行广告文案匹配搜索
3 - 广告主,用户输入的keyword将会对广告主进行搜索
4 - 着陆页url,用户输入的keyword将会对落地页链接、重定向链接进行搜索
5 - 电商产品,用户输入的keyword将会对电商产品名称进行搜索
6 - TikTok Shop店铺,用户输入的keyword将会对TikTok Shop店铺名称进行搜索
7 - APP名称,用户输入的keyword将会对App应用名称进行搜索
8 - APP开发者,用户输入的keyword将会对APP开发者名称进行搜索
9 - 社媒账号 (主页名称),用户输入的keyword将会对社媒账号 (TT账号/Page ID)进行搜索
10 - 素材 (脚本/钩子/标签),用户输入的keyword素材信息 (脚本/钩子/标签)进行搜索
11 - 电商店铺/URL,用户输入的keyword将会对电商店铺/URL进行搜索
12 - TikTok Shop产品,用户输入的keyword将会对TikTok Shop产品进行搜索

ExcludeWordVo 结构:

字段名 类型 必填 描述
keyword String 是 排除关键词
type int 是 排除类型,取值同 ExtendKeyWordsVo

可选参数 - 店铺与产品

参数名 类型 必填 描述
shop_type List<String> 否 商店类型列表:
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 否 根路径
is_tiktok_shop Boolean 否 是否为TikTok Shop
product_id String 否 产品ID
tk_shop_category_id List<String> 否 TikTok Shop分类ID列表
product_category_id List<String> 否 电商分类ID列表,和广告产品页面分类相同

可选参数 - APP相关

参数名 类型 必填 描述
is_app Boolean 否 是否为应用广告
app_system String 否 应用平台:ios/android,支持逗号分割的多平台
app_type String 否 应用类型
app_category List<String> 否 应用分类列表
app_dev_id String 否 应用开发者ID
app_id String 否 应用ID

可选参数 - 互动数据范围

参数名 类型 必填 描述
play_count_min Long 否 播放次数最小值
play_count_max Long 否 播放次数最大值
digg_count_min Long 否 点赞次数最小值
digg_count_max Long 否 点赞次数最大值
comment_count_min Long 否 评论次数最小值
comment_count_max Long 否 评论次数最大值
share_count_min Long 否 分享次数最小值
share_count_max Long 否 分享次数最大值
download_count_min Long 否 下载次数最小值
download_count_max Long 否 下载次数最大值
hot_value_min Long 否 热度值最小值(热度值=点赞数+评论数+分享数)
hot_value_max Long 否 热度值最大值
digg_rate_min Double 否 点赞率最小值
digg_rate_max Double 否 点赞率最大值
share_play_rate_min Double 否 分享播放率最小值
share_play_rate_max Double 否 分享播放率最大值

可选参数 - Facebook互动数据

参数名 类型 必填 描述
reaction_wow_min Long 否 Facebook反应"Wow"最小值
reaction_wow_max Long 否 Facebook反应"Wow"最大值
reaction_love_min Long 否 Facebook反应"Love"最小值
reaction_love_max Long 否 Facebook反应"Love"最大值
reaction_haha_min Long 否 Facebook反应"Haha"最小值
reaction_haha_max Long 否 Facebook反应"Haha"最大值
reaction_sad_min Long 否 Facebook反应"Sad"最小值
reaction_sad_max Long 否 Facebook反应"Sad"最大值
reaction_anger_min Long 否 Facebook反应"Anger"最小值
reaction_anger_max Long 否 Facebook反应"Anger"最大值
reaction_care_min Long 否 Facebook反应"Care"最小值
reaction_care_max Long 否 Facebook反应"Care"最大值

可选参数 - 时间范围

参数名 类型 必填 描述
create_time_start Long 否 创建时间开始(Unix时间戳,秒)
create_time_end Long 否 创建时间结束(Unix时间戳,秒)
first_time_start Long 否 首次发现时间开始(Unix时间戳,秒)
first_time_end Long 否 首次发现时间结束(Unix时间戳,秒)
last_time_start Long 否 最后修改时间开始(Unix时间戳,秒)
last_time_end Long 否 最后修改时间结束(Unix时间戳,秒)
put_day_min Long 否 投放天数最小值
put_day_max Long 否 投放天数最大值
release_time_start Long 否 APP上架时间开始(Unix时间戳,秒)
release_time_end Long 否 APP上架时间结束(Unix时间戳,秒)

可选参数 - 广告属性

参数名 类型 必填 描述
formate_type List<Integer> 否 广告格式类型列表
button List<String> 否 按钮类型列表
age List<String> 否 年龄范围列表,格式如"18-24"
sex List<Integer> 否 性别列表:0-全部,1-男性,2-女性
is_url Integer 否 URL 状态:0-无落地页链接,1-有落地页链接
is_ad_fake Boolean 否 是否是非品牌广告(非Tiktok Spark Ads)
is_product Boolean 否 是否为产品广告
is_redirect Boolean 否 是否有重定向URL
ad_duration_min Long 否 广告时长最小值(秒)
ad_duration_max Long 否 广告时长最大值(秒)
size List<String> 否 画面比例列表:1:1、16:9、4:3、9:16、21:9、1:2、3:4、4:5、2:1、5:4
clarity List<String> 否 画质列表:SD、HD、Full HD、UHD/4K、8K
aspect_ratio List<String> 否 分辨率列表:640×360、360×640、854×480、480×854、720×720、1080×1080等
ad_status String 否 广告状态:0-已停止,1-投放中,使用逗号分割
ad_state Integer 否 广告状态:0-已停止,1-投放中
is_real String 否 是否真人:no-AI,yes-真人,为空默认查全部

可选参数 - 广告成本与转化

参数名 类型 必填 描述
ad_cost_min Double 否 广告花费最小值
ad_cost_max Double 否 广告花费最大值
estimated_conversion_min Double 否 预估转化最小值
estimated_conversion_max Double 否 预估转化最大值

可选参数 - APP数据

参数名 类型 必填 描述
monthly_install_min Long 否 APP月安装量最小值
monthly_install_max Long 否 APP月安装量最大值
monthly_income_min Double 否 APP月收入最小值
monthly_income_max Double 否 APP月收入最大值
score_min Double 否 APP评分最小值
score_max Double 否 APP评分最大值

可选参数 - AI分析与分类

参数名 类型 必填 描述
ai_analysis_tags List<String> 否 AI分析标签列表,使用脚本分析标签查询
ai_category List<String> 否 AI分类列表,使用toolify上的AI分类(暂未使用)
skits_category List<String> 否 短剧分类列表(暂未使用)
interest String 否 兴趣标签

可选参数 - 其他

参数名 类型 必填 描述
popular_person_id String 否 红人ID
exclude_history Integer 否 是否排除浏览历史:1-排除
is_recommend Integer 否 是否为推荐内容
sort Integer 否 排序方式:
13-按图片相似度排序
3-首次发现时间
4-广告播放
5-投放天数
6-互动数
7-点赞率
8-转发比
9-点赞数
10-评论数
11-分享数
12-创建时间
sort_type String 否 排序类型:desc-降序,asc-升序
user_search_time Long 否 用户搜索时间(Unix时间戳,秒)
after String[] 否 游标分页参数

请求示例

基础请求示例

使用 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
    }
  }'

高级过滤示例

使用关键词和地区过滤

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"
    }
  }'

响应参数

响应体结构

{
  "code": 200,
  "message": "success",
  "data": {
    "data": [ ... ],
    "page": { ... }
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}

响应字段说明

顶层字段

字段名 类型 描述
code Integer 响应状态码,200 表示成功
message String 响应消息
data Object 响应数据,包含 data(广告列表)和 page(分页信息)
version String API 版本
timestamp String 响应时间戳
sign String 响应签名
remaining_credits Long 当前请求后的剩余可用积分
consumed_credits Long 本次请求消耗的积分
success Boolean 请求是否成功
fail Boolean 请求是否失败
广告数据字段 (data) - 按字母顺序
字段名 类型 描述
id string 视频 ID (访问广告详情用此字段作为id)
video_id string 视频 ID (访问广告详情用此字段作为id)
ad_create_time number 广告创建时间(时间戳)
ai_analysis_human_presenter string AI 分析人类演示者
ai_analysis_language string AI 分析语言
ai_analysis_main_hook string AI 分析主要钩子
ai_analysis_script string AI 分析脚本
ai_analysis_tags array[string] AI 分析标签列表
app_dev_id string 应用开发者 ID
app_image string 应用图片 URL
app_name string 应用名称
app_title string 应用标题
button_text string 按钮文本
carousel array[object] 轮播图列表
comment_count number 评论数
cover string 封面图片 URL
data_type array[number] 数据类型列表
desc string 广告描述
digg_count number 点赞数
digg_play_rate number 点赞播放率
duration number 时长(秒)
facebook_link_angry number Facebook 愤怒反应数
facebook_link_care number Facebook 关心反应数
facebook_link_haha number Facebook 哈哈反应数
facebook_link_love number Facebook 喜欢反应数
facebook_link_sad number Facebook 悲伤反应数
facebook_link_wow number Facebook 惊讶反应数
fetch_region array[string] 抓取地区列表
found_time number 发现时间(时间戳)
had_ai_analysis boolean 是否进行过 AI 分析
have_tiktok_shop boolean 是否有 TikTok 商店
hot_value number 热度值
image string 图片 URL
is_collection boolean 是否收藏
is_download boolean 是否可下载
last_put_time number 最后投放时间(时间戳)
min_cpa number 最小预估转换,由PIPIADS根据大数据和目标地区通用订单CPA指标自动计算而来(含误差)
min_cpm number 最小广告花费,由PIPIADS根据大数据和目标地区通用CPM指标自动计算而来(含误差)
modify_time number 修改时间(时间戳)
pack_url string 包 URL
platform number 平台类型(1:Facebook, 2:Instagram, 3:TikTok)
play_count number 播放数
put_days number 投放天数
root_path_id string 广告主 ID
search_by_image_tag boolean 是否通过图片标签搜索
share_count number 分享数
share_play_rate number 分享播放率
shop_type string 商店类型
type number 广告类型(1:视频, 2:图片)
video_url string 视频 URL
_score Number 搜索关键字分数
字段名 类型 描述
aspect_ratio string 宽高比
body string 正文内容
button_text string 按钮文本
cta_text string CTA 文本
cover string 封面图片 URL
cover_could_storage string 封面云存储
dimensions_type number 尺寸类型
duration number 时长(秒)
height number 高度
image string 图片 URL
image_could_storage string 图片云存储
link_description string 链接描述
link_url string 链接 URL
play_count number 播放次数
quality string 质量
resolution string 分辨率
title string 标题
type number 类型
video_audio_user_preferred_language string 视频音频用户首选语言
video_url string 视频 URL
video_url_could_storage string 视频 URL 云存储
width number 宽度
分页信息字段 (page)
字段名称 类型 描述
total_count number 总记录数
page_count number 总页数
current_page number 当前页码
page_size number 每页大小
is_next boolean 是否有下一页

响应示例

{
  "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
}

错误码说明

错误码 描述
200 成功
400 请求参数错误
401 未授权 - API 密钥无效
500 服务器内部错误

相关接口

完整的以图搜广告流程涉及以下接口:

  1. 图片提交:/v3/api/open/ai-search/image/submit 或 /v3/api/open/ai-search/image/submit/image-url
  2. 处理状态查询:/v3/api/open/ai-search/image/status
  3. 结果摘要:/v3/api/open/ai-search/image/resultSummary
  4. 广告搜索(本接口):/v3/api/open/ai-search/image/search4/ad/search
  5. 产品搜索:/v3/api/open/ai-search/image/product/search
  6. 店铺搜索:/v3/api/open/ai-search/image/root-path/search
  7. TikTok产品搜索:/v3/api/open/ai-search/image/tiktok-product/search
  8. TikTok店铺搜索:/v3/api/open/ai-search/image/tiktok-shop/search