Pipispy APIEnglish

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

Adspy 详情接口

接口信息

  • 接口名称: 获取 Adspy 详情
  • 请求方法: POST
  • 接口地址: /open-api/v1/data
  • 接口路径: /v3/api/open/adspy/detail
  • 接口描述: 根据广告 ID 获取 Adspy 详细信息
  • 价格说明: 详情接口计费规则: 基础费用:1 credit/次。 免费访问条件(满足其一即可): 该ID在3天内已获取过详情;该ID在3天内出现在您的榜单列表查询结果中。

请求头:

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

请求参数

请求结构

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

参数列表 (params 对象)

参数名 类型 必填 描述
id String 是 广告素材唯一标识。使用 Adspy 列表接口返回的 video_id

请求示例

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/adspy/detail",
    "params": {
      "id": "1795208137186337"
    }
  }'

响应参数

响应体结构

{
  "code": 200,
  "message": "success",
  "data": {},
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}

响应字段说明

字段名 类型 描述
code Integer 业务响应状态码;200 表示请求处理成功,其他值表示请求失败
message String 响应说明;失败时用于描述参数错误、数据不存在等原因
data Object/null Adspy 详情对象;未查询到对应广告时可能为 null
version String 当前开放 API 响应版本,例如 v1
timestamp Number/null 网关响应时间戳;未启用时为 null
sign String/null 响应签名;未启用签名校验时为 null
remaining_credits Long 本次请求完成后,API key 剩余的可用积分数量
consumed_credits Long 本次请求实际消耗的积分数量;命中免费访问条件时可能为 0
success Boolean 业务请求是否成功;成功为 true
fail Boolean 业务请求是否失败;失败为 true,与 success 含义相反

Adspy 详情字段

字段使用说明:

  • 所有时间字段均为 Unix 秒级时间戳,例如 1752199828;调用方应按自身时区转换展示。
  • 播放、点赞、评论、分享、收藏等指标是最近一次采集到的累计值,不保证与媒体平台页面实时一致。
  • URL 字段可能因源广告下线、地区限制或媒体平台鉴权而失效,调用方应做好访问失败处理。
  • 非当前广告类型或平台适用的字段可能返回 null、空字符串、空数组,或不出现在响应中;不应以字段是否存在判断请求是否成功。
  • Number/String、Array/String 等联合类型是为了兼容历史数据,建议调用方反序列化时允许对应的多种类型。
字段名 类型 描述
active_status Number 告活跃状态,与列表接口 ad_state 判断口径一致, PipiAds 根据最近一次监测时间判断的投放状态:当广告的 modify_time 晚于当前服务日期,表示近期仍监测到广告数据变化,返回 1(监测中/可能仍在投放);当 modify_time 不晚于当前服务日期,表示近期未再监测到更新,返回 0(已停止或暂未监测到投放)
ad_advertiser Object/null 广告主信息;无法关联到广告主时为 null,子字段见下文
ad_create_time Number 广告在媒体平台上的创建或首次发布时间,Unix 秒级时间戳
ad_developer Object/null 与广告关联的应用开发者信息;非 App 广告或未关联时为 null
ad_fee Long 兼容统计值,服务端按 play_count / 1000 计算;不是媒体账户实际广告费用。页面展示的广告花费区间由 CPM 估算字段计算
ad_id String 媒体平台提供的广告 ID。同一广告素材可能对应不同的 ad_id 与 video_id
ad_shop Object/null 广告关联的 TikTok Shop 店铺信息;非 TikTok Shop 广告时为 null
ad_store Object/null 广告落地页对应的网站或独立站信息;无法识别店铺时为 null
aigc_label_type Number/null AI 广告视频标记:0 或 null 表示非 AI 广告视频;非 0 且非 null 表示 AI 广告视频,具体数值代表相应的 AIGC 类型
ai_analysis Object/null 视频内容的 AI 分析结果;非视频广告或尚未完成分析时可能为 null
app_dev Object/null 应用开发者原始信息;常见字段包括 id、name、icon、url
app_image String 广告主头像、TikTok 账号头像或应用图标的完整 URL
app_info Object/null 广告关联的应用详情,包括应用名称、评分、下载量、分类及收入等信息;非 App 广告时为 null
app_name String 广告主名称。TikTok 广告通常为账号昵称,Facebook 广告通常为主页或广告主名称
app_store String 应用商店标识,例如 apple、google;非 App 广告可能为空
app_system String 应用操作系统,例如 ios、android;非 App 广告可能为空
app_type String 广告推广对象类型,例如 app、game、web
app_url String 用户点击广告后访问的落地页、应用商店页或商品详情页 URL
age_range Array 原始受众年龄区间列表;无数据时服务端通常补为空数组;页面展示优先使用 audience.age
aspect_ratio String 详情接口标准化后的素材尺寸字符串,TikTok 通常为 宽x高(例如 576x1024);不是严格的数学宽高比
ad_category Array 原始广告分类列表;无数据时服务端通常补为空数组
audience Object 广告受众概览,包括覆盖人数、地区、年龄、性别和来源等信息
carousel Array 轮播广告的素材卡片列表;仅 type=3 时有值,子字段见下文
clarity String/null 视频质量标签,例如 SD、HD;无法识别时为 null
collect_count Number 媒体平台采集到的累计收藏次数;平台不提供时通常为 0
comment_count Number 媒体平台采集到的累计评论次数
content_list Array 标准化后的广告文案、CTA 和落地页列表;轮播广告可能包含多条内容
cover String 视频封面图片的完整 URL;图片广告或无封面时可能为空字符串
data_type String/null 广告业务分类集合的字符串表示,例如 "[3,4]";详情接口与列表接口不同,不能按 JSON 数组直接解析;枚举含义见下文
digg_count Number 媒体平台采集到的累计点赞次数
digg_play_rate Number 点赞率,取值通常为 0 至 1 的小数;例如 0.0033 表示约 0.33%
download_count Number 媒体平台采集到的累计下载次数;平台不提供时通常为 0
duration Number/String 视频时长,单位为秒;非视频或无法获取时可能为空字符串,调用方需兼容两种类型
fetch_region Array/String 兼容字段;有地区数据时通常为国家/地区数组,字段缺失时可能为空字符串;广告投放国家/地区请使用 audience.region
facebook_category Array/null Facebook 对该广告标注的类别列表;非 Facebook 广告通常为空或不返回
facebook_display_format String Facebook 广告展示形式,例如视频、图片或轮播;非 Facebook 广告可能为空
facebook_like_info Array/null Facebook 表情互动统计列表;数组元素含互动类型及数量,子字段见下文
facebook_link String Facebook 广告、帖子或广告资料库页面 URL;非 Facebook 广告可能为空
forward_count Number 媒体平台采集到的累计转发次数;不支持该指标的平台通常返回 0
found_time Number PipiAds 首次发现该广告的时间,Unix 秒级时间戳;不等同于广告创建时间
hot_value Number PipiAds 广告热度指标,用于衡量广告当前受关注程度;数值越大通常代表热度越高
image String 图片广告主图的完整 URL;视频广告通常为空字符串
isSpark Boolean 兼容派生字段;当前由 is_ad_fake 反向推导,不能作为媒体平台官方 Spark Ads 身份的绝对依据;无原始标记时可能不返回
is_ad_fake Boolean/null 广告真实性识别标记:true 疑似搬运或非原生广告,false 非疑似,未识别时为 null
is_collection Boolean 当前 API key 所属账号是否已收藏该广告
is_download Boolean 当前 API key 是否具有该素材的下载权限;不代表素材 URL 一定有效
label Object/null 广告的人工或系统分类标签;无标签时为 null,可包含中英文标签名称
language Array 广告内容语言代码列表,例如 ["en"]、["zh-cn"];通常采用 ISO 语言代码
last_put_time Number 最近一次监测到广告投放的时间,当前服务端取 modify_time,Unix 秒级时间戳
max_cpa Number/null 最大 CPA,由PIPIADS根据大数据和目标地区通用订单CPA指标自动计算而来(含误差),无法估算时为 null
max_cpm Number/null 最大 CPM,由PIPIADS根据大数据和目标地区通用CPM指标自动计算而来(含误差),无法估算时为 null
min_cpa Number/null 最小 CPA,由PIPIADS根据大数据和目标地区通用订单CPA指标自动计算而来(含误差), 无法估算时为 null
min_cpm Number/null 最小 CPM,由PIPIADS根据大数据和目标地区通用CPM指标自动计算而来(含误差),无法估算时为 null
modify_time Number 最近一次监测到广告仍在投放或数据发生变化的时间,Unix 秒级时间戳
music_id String TikTok 视频使用的音乐或声音 ID;其他平台可能为空
music_name String TikTok 视频使用的音乐或声音名称;其他平台可能为空
music_url String TikTok 视频音乐或声音资源 URL;其他平台可能为空
pack_url String 应用安装包下载 URL;无安装包信息时为空字符串
platform Number 平台类型:1 TikTok,2 Facebook
play_count Number 媒体平台采集到的累计播放或展示次数;具体口径取决于媒体平台
popular_person_id String/null 与 TikTok 作者关联的 PipiAds 红人档案 ID;未关联时不返回或为 null
product_currency String 商品价格币种代码,例如 USD、THB
product_id String PipiAds 关联商品 ID;
product_image String 关联商品主图的完整 URL
product_price String 商品价格字符串;可能包含小数或货币符号,建议按字符串展示
product_title String 关联商品名称或标题
publisher_platform Array 广告实际发布的平台列表,例如 ["facebook","instagram"] 或 ["tiktok"]
put_days Number 广告累计监测投放天数
resolution String 素材分辨率,格式通常为 宽x高,例如 540x960
root_path String 从广告落地页提取的根域名,例如 example.com;不是完整 URL
root_path_id String PipiAds 中该根域名/广告主档案的唯一 ID
search_by_image_tag Boolean 是否支持基于该广告关联商品图进行图片相似搜索
share_count Number 媒体平台采集到的累计分享次数
size String/null 素材画面比例或尺寸标签,例如 9:16;无法识别时为 null
shop_type String/null 落地页识别出的建站或电商平台类型,例如 Shopify;无法识别或非电商网站时为 null
source Array 广告来源设备或系统列表,例如 ["Android"]
tiktok_author String TikTok 发布账号的用户名,即主页 @ 后的名称
tiktok_author_url String TikTok 发布账号主页的完整 URL
tiktok_shop Array 广告挂载的 TikTok Shop 商品列表;可包含多个商品,子字段见下文
type Number 素材类型:1 视频、2 图片、3 轮播
update_time Number 详情数据更新时间;TikTok 当前取 modify_time,Facebook 取 facebook_update_time,Unix 秒级时间戳
url String 广告在媒体平台上的帖子或广告链接;TikTok 由素材 ID 组装,Facebook 通常取 facebook_link;与外部落地页 app_url 不同
url_history Array 广告落地页曾解析到的跳转 URL 列表;可用于还原重定向链路
video_id String PipiAds 广告素材唯一 ID,也是调用本详情接口时推荐使用的 id
video_url String 视频文件的完整 URL;仅视频或含视频的轮播素材有值

字段枚举说明

字段名 值 描述
platform 1 TikTok 广告
platform 2 Facebook/Meta 广告,可能发布在 Facebook、Instagram 等版位
type 1 视频素材
type 2 单图片素材
type 3 轮播素材,具体卡片见 carousel
data_type 1 产品广告/爆品跟卖广告
data_type 2 TikTok Shop 小店广告
data_type 3 Web 电商广告
data_type 4 品牌或 Spark Ads 类广告
data_type 5 游戏广告
data_type 6 App 应用广告
data_type 7 AI App 广告
data_type 8 短剧 App 广告
data_type 9 AI Web 广告
data_type 10 短剧 Web 广告

data_type 允许同时包含多个分类。例如字符串 "[2,3,4]" 表示该广告同时具有 TikTok Shop、电商和品牌/Spark Ads 属性。

AI 分析字段 (ai_analysis 对象)

字段名 类型 描述
ai_analysis_language String AI 识别出的广告主要语言代码,例如 en、zh-cn
ai_analysis_human_presenter String AI 判断素材中是否有真人出镜或讲解;返回字符串形式,如 yes、no、true、false
ai_analysis_main_hook String AI 提取的主要营销钩子、开场卖点或吸引用户注意的核心表达
ai_analysis_script String 从视频语音、字幕和画面中识别整理出的广告脚本文本
ai_analysis_tags Array AI 提取的主题、商品、场景及卖点标签列表,例如 ["#shoes","#sale"]

受众信息字段 (audience 对象)

字段名 类型 描述
gender Array 受众性别列表;可能包含 all、men、women,无数据时为空数组
covered Number/null 估算覆盖人数;TikTok 广告通常表示播放覆盖量,Facebook 广告表示可获取的受众触达量
source Array 受众来源设备或系统列表,例如 ["Android"]
region Array 受众国家/地区代码列表,例如 ["TH"]
category Array 广告或受众兴趣分类列表
age Array 年龄区间列表,例如 ["25-35","35-45"]
max_data Object Facebook 受众中占比最高的地区和年龄段摘要;无受众明细时不返回

Facebook 受众摘要字段 (audience.max_data 对象)

字段名 类型 描述
region String 覆盖人数最多的国家/地区代码
ragion_rate Number 覆盖人数最多地区的占比,取值 0 至 1;字段名按接口实际拼写返回
age String 覆盖人数最多的年龄区间
age_rate Number 覆盖人数最多年龄区间的占比,取值 0 至 1

内容列表字段 (content_list 数组对象)

字段名 类型 描述
cta String 行动号召按钮文案,例如 Shop Now、Learn More、立即购买
cta_text String Facebook 轮播卡片的行动号召文案;仅部分轮播内容返回
caption String Facebook 广告卡片的标题或简短说明
landing_page String 用户点击该条内容后进入的落地页 URL
title String 广告标题、应用名或轮播卡片标题
desc String 广告正文、视频描述或卡片正文
url_history Array 该条内容对应的落地页跳转 URL 列表
link_description String Facebook 广告链接下方展示的补充描述文本

TikTok 商店字段 (tiktok_shop 数组对象)

字段名 类型 描述
new_source Number 商品数据来源标记;用于区分不同商品数据渠道,调用方可作为透传字段保存
image String TikTok Shop 商品主图的完整 URL
product_id String TikTok Shop 平台商品 ID,可用于唯一标识商品
shop_id String 商品所属 TikTok Shop 店铺 ID
real_price String 商品当前展示价格,通常包含货币符号,例如 $10.04
original_price String 商品划线价或优惠前价格;无折扣信息时可能为空
title String TikTok Shop 商品完整标题
category_id_list Array TikTok Shop 商品所属类目的 ID 列表,可能包含多级类目
url String TikTok Shop 商品详情页完整 URL
sold_count Number 商品页面展示的累计销量

规范化关联对象字段 (ad_advertiser、ad_store、ad_shop、ad_developer 对象)

字段名 类型 描述
id String/null 关联对象在 PipiAds 或对应媒体平台中的唯一 ID
store_id String/null 广告主所关联的网站/店铺 ID;仅 ad_advertiser 可能返回
name String/null 广告主、网站店铺、TikTok 小店或应用开发者名称
avatar String/null 广告主头像、店铺图片或开发者图标的完整 URL
link String/null 广告主根域名、店铺主页或开发者页面链接

Facebook 互动字段 (facebook_like_info 数组对象)

字段名 类型 描述
count Number 对应互动类型的累计次数
id String Facebook 互动类型 ID;无平台 ID 时可能为空
localized_name String 互动类型的本地化名称,例如 Like、Love、Wow、Haha、Sad、Angry、Care
字段名 类型 描述
type Number 卡片素材类型:1 视频,2 图片
image String 图片卡片的素材 URL
video_url String 视频卡片的视频 URL
cover String 视频卡片的封面 URL
duration String/Number 视频卡片时长;原始数据可能以字符串返回,单位为秒
title String 卡片标题
body String 卡片正文
caption String 卡片简短说明;部分 Facebook 数据返回
cta_text String 卡片行动号召文案
link_url String 卡片点击后访问的落地页 URL
link_description String 卡片链接补充描述
url_history Array 卡片落地页的跳转 URL 列表
aspect_ratio String 素材宽高比,例如 9:16
quality String 素材质量标签,例如 SD、HD
resolution String 素材分辨率,例如 1080x1920

应用开发者字段 (app_dev 对象)

字段名 类型 描述
id String 应用开发者唯一 ID
name String 应用开发者名称
icon String 开发者图标或头像的完整 URL
url String 开发者在应用商店或官方网站的页面 URL

应用信息字段 (app_info 对象)

字段名 类型 描述
id String 应用唯一 ID;该值可能经过脱敏,仅用于当前开放 API 数据关联
name String 应用商店中展示的应用名称
url String 应用商店详情页 URL
icon String 应用图标 URL
download Number 应用累计下载量或应用商店展示的下载量
app_comment_count Number 应用累计评论数量
category Object 应用分类信息,子字段见下文
rate Object 应用评分信息,子字段见下文
revenue Object/null 应用收入信息;无可用收入数据时为 null,子字段见下文
last_month_app_download_count Number 应用最近一个自然月的下载量估算值
create_time Number 应用记录创建时间,Unix 秒级时间戳

应用评分字段 (app_info.rate 对象)

字段名 类型 描述
score Number 应用综合评分
count Number 参与评分的用户数量
rate1 Number 一星评分数量
rate2 Number 二星评分数量
rate3 Number 三星评分数量
rate4 Number 四星评分数量
rate5 Number 五星评分数量

应用分类字段 (app_info.category 对象)

字段名 类型 描述
id String 应用分类 ID
name String 应用分类名称
type String 分类类型或层级
app_system String 分类适用的应用系统,例如 ios、android
children Array 子分类列表;元素可包含 id、name、type、app_system

应用收入字段 (app_info.revenue 对象)

字段名 类型 描述
value Number 收入数值
unit String 金额单位,例如 cent 表示分
currency String 货币代码,例如 USD
type String 数值类型,例如 currency

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "comment_count": 1,
    "forward_count": 0,
    "pack_url": "",
    "source": ["Android"],
    "type": 1,
    "resolution": "540x960",
    "ai_analysis": {
      "ai_analysis_language": "zh-cn",
      "ai_analysis_human_presenter": "yes",
      "ai_analysis_main_hook": "你在偷拍什么呀?",
      "ai_analysis_script": "你在偷拍什么呀?泰国DTV签证,不用出境也能办理。快至七天获批,9000元起就够,五年内有效期,无限次往返泰国,一次可待180天。不过可以申请退费,点击下方链接立即申请。",
      "ai_analysis_tags": [
        "#DTV签证",
        "#泰国",
        "#不用出境",
        "#办理",
        "#七天获批",
        "#9000元起",
        "#五年有效期",
        "#无限次往返",
        "#180天",
        "#申请退费",
        "#下方链接",
        "#立即申请",
        "#签证"
      ]
    },
    "cover": "https://cdn-video.pipispy.com/cover_6f730728bdc01d3cdce00223de09fc4f.jpg",
    "max_cpm": 2.4,
    "last_put_time": 1752199828,
    "root_path_id": "682e25abe87d0e8f5818189b",
    "put_days": 2,
    "image": "",
    "audience": {
      "gender": [],
      "covered": 909,
      "source": ["Android"],
      "region": ["TH"],
      "category": [],
      "age": ["35-45"]
    },
    "play_count": 909,
    "ad_create_time": 1751942170,
    "found_time": 1752067470,
    "ad_id": "1837044055239874",
    "root_path": "ccddsite88.net",
    "digg_count": 3,
    "content_list": [
      {
        "cta": "เรียนรู้เพิ่มเติม",
        "landing_page": "https://ccddsite88.net/landing-page/thailand/tk/1747707570548/?ttclid=E_C_P_CssBEU5QXACDVfMYNCqcBdOW23Ndidd7knaaqh33vgz0N3--FsUbYw0wC8RfDBrdG6Q0HLWvHnPjwINxzZrvXXozfcERzmjOAnAaD-B-tVEeQ1fnAfs3uWEPeRU9_45T4jl7QSzD1Zi-zQLz4IwgsHo2ssq9veFvzuXZnpw0b6lZcNRonZMSZBRxG-cjyUsRIvMKn-qkMV3Q1kCD2niYVect6n7ZTSrHK8f894b_6_5V7_sD2zGP2hudN80m55zW5hBOeM9tzNMJXreMoIoSBHYyLjA",
        "title": "即日起,泰国DTV满足这2个条件即可,快至7天,不过可退!",
        "desc": "即日起,泰国DTV满足这2个条件即可,快至7天,不过可退!",
        "url_history": []
      }
    ],
    "is_download": false,
    "publisher_platform": ["tiktok"],
    "aspect_ratio": "540x960",
    "digg_play_rate": 0.0033,
    "modify_time": 1752199828,
    "min_cpa": 0.0,
    "is_collection": false,
    "platform": 1,
    "duration": 17,
    "update_time": 1752199828,
    "video_url": "https://cdn-video.pipispy.com/video_1cd71dc2169dd279821b1ba4736d4e19.mp4",
    "tiktok_author_url": "https://www.tiktok.com/@泰国DTV",
    "ad_fee": 0,
    "min_cpm": 0.6,
    "app_url": "https://ccddsite88.net/landing-page/thailand/tk/1747707570548/?ttclid=E_C_P_CssBEU5QXACDVfMYNCqcBdOW23Ndidd7knaaqh33vgz0N3--FsUbYw0wC8RfDBrdG6Q0HLWvHnPjwINxzZrvXXozfcERzmjOAnAaD-B-tVEeQ1fnAfs3uWEPeRU9_45T4jl7QSzD1Zi-zQLz4IwgsHo2ssq9veFvzuXZnpw0b6lZcNRonZMSZBRxG-cjyUsRIvMKn-qkMV3Q1kCD2niYVect6n7ZTSrHK8f894b_6_5V7_sD2zGP2hudN80m55zW5hBOeM9tzNMJXreMoIoSBHYyLjA",
    "fetch_region": "",
    "max_cpa": 1.0,
    "url": "https://m.tiktok.com/v/7524534322666228999.html",
    "collect_count": 1,
    "download_count": 0,
    "share_count": 0,
    "tiktok_author": "泰国DTV",
    "app_name": "泰国DTV",
    "active_status": 1,
    "hot_value": 4,
    "data_type": "[4]",
    "url_history": [],
    "video_id": "496b74d6a6135f80c17d",
    "app_image": "https://cdn-video.pipispy.com/avatar_5eabd0708ef037d43a4377d740ae2c53.jpg"
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 1,
  "success": true,
  "fail": false
}

错误码说明

错误码 描述
200 请求处理成功;请继续检查 data 是否为 null,data=null 表示未查询到对应广告
400 请求参数错误,例如 params.id 缺失、为空或格式不受支持
404 部分网关或历史版本在广告不存在时可能返回该状态;当前调用方仍应兼容 200 且 data=null
500 服务内部错误或依赖服务异常;建议记录 message,并采用有限次数的退避重试