广告库详情接口
API 信息
- API 名称: 获取广告库详情
- 请求方法: POST
- API 地址:
/open-api/v1/data
- 接口路径:
/v3/api/open/lib-ads/detail
- 接口描述: 根据广告 ID 获取广告详细信息,包含广告历史变化数据
- 价格说明: 详情接口计费规则: 基础费用:1 credit/次。 免费访问条件(满足其一即可): 该ID在3天内已获取过详情;该ID在3天内出现在您的榜单列表查询结果中。
请求头设置:
- Content-Type: application/json
- Accept: application/json
请求参数
请求结构
| 参数名称 |
类型 |
描述 |
示例 |
必填 |
默认值 |
| key |
string |
用户申请的外部 API 请求 key |
"your_api_key_here" |
是 |
|
| uri |
string |
接口 URI 路径 |
"/v3/api/open/lib-ads/detail" |
是 |
|
| params |
object |
接口参数对象 |
见下方参数列表 |
是 |
|
参数列表 (params 对象)
| 参数名称 |
类型 |
描述 |
示例 |
必填 |
默认值 |
| id |
string |
广告 ID,系统内部唯一标识 |
"06c7df340f26f2539c8dada9fa5afe27" |
是 |
|
请求示例
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/lib-ads/detail",
"params": {
"id": "06c7df340f26f2539c8dada9fa5afe27"
}
}'
响应
响应体结构
{
"code": 200,
"message": "success",
"data": {
"ads_history": {
// 广告历史变化数据
},
"advertisement": {
// 广告详细信息
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 1,
"success": true,
"fail": false
}
响应字段说明
主要响应字段
| 字段名称 |
类型 |
描述 |
| ads_history |
object |
广告历史变化数据 |
| advertisement |
object |
广告详细信息 |
| version |
string |
API 版本号 |
| timestamp |
long |
响应时间戳 |
| sign |
string |
响应签名 |
| remaining_credits |
Long |
当前请求后的剩余可用积分 |
| consumed_credits |
Long |
本次请求消耗的积分 |
| success |
boolean |
请求是否成功 |
| fail |
boolean |
请求是否失败 |
广告历史字段 (ads_history)
| 字段名称 |
类型 |
描述 |
| ad_cost |
object |
广告花费历史数据 |
| adset_count |
object |
广告组数历史数据 |
历史数据时间线字段 (timeline)
| 字段名称 |
类型 |
描述 |
| count |
double |
数值 |
| date |
string |
日期 (YYYY-MM-DD 格式) |
广告详情字段 (advertisement)
| 字段名称 |
类型 |
描述 |
| id |
string |
广告 ID,系统内部唯一标识 |
| active_days |
long |
广告投放天数 |
| ad_audience |
object |
广告受众信息 |
| ad_audience_reach |
long |
广告触达人数 |
| ad_caption |
string |
广告描述 |
| ad_content |
string |
广告文案内容 |
| ad_cost |
double |
广告花费金额 |
| ad_forecast |
long |
广告预测状态 (1:Testing 2:Scaling 3:Winning) |
| ad_link |
string |
广告链接 |
| ad_link_description |
string |
广告链接描述 |
| ad_platform |
array |
广告投放平台列表 |
| ad_started_at |
long |
广告创建时间 |
| ad_status |
long |
广告状态 (1:活跃 2:不活跃 3:下架) |
| ad_title |
string |
广告标题 |
| adset_count |
long |
广告组数量 |
| advertiser |
object |
广告主信息 |
| button_text |
string |
按钮文本 |
| button_type |
string |
按钮类型 |
| cards |
array |
轮播图列表 |
| country |
array |
投放国家列表 |
| first_discovered_at |
long |
广告首次发现时间 |
| images |
array |
广告图片列表 |
| landing_page_type |
long |
落地页类型 |
| landing_pages |
array |
落地页 URL 列表 |
| language |
string |
广告语言 |
| last_discovered_at |
long |
广告最后更新时间 |
| latest_actived_at |
long |
广告最后活跃时间 |
| media_format |
long |
媒体格式类型 |
| products |
array |
广告产品列表 |
| source_ad_id |
string |
源广告 ID |
| store |
object |
广告店铺信息 |
| user_collected |
long |
用户是否收藏 (1:已收藏 2:未收藏) |
| videos |
array |
广告视频列表 |
| size |
string |
尺寸信息 |
| clarity |
string |
清晰度信息 |
| aspect_ratio |
string |
宽高比信息 |
| ai_analysis |
object |
AI 分析结果 |
AI 分析对象字段 (ai_analysis)
| 字段名称 |
类型 |
描述 |
| ai_analysis_human_presenter |
string |
是否真人演示者 |
| ai_analysis_language |
string |
视频语言 |
| ai_analysis_main_hook |
string |
主要钩子内容 |
| ai_analysis_script |
string |
视频脚本 |
| ai_analysis_tags |
array |
视频标签列表 |
广告主信息对象字段 (advertiser)
| 字段名称 |
类型 |
描述 |
| id |
string |
广告主 ID |
| name |
string |
广告主名称 |
| ad_count |
long |
广告主广告数量 |
| ad_country |
array |
广告主投放国家 |
| ads_library_link |
string |
广告库链接 |
| adset_count |
long |
广告组数量 |
| e_commerce_platform |
string |
电商平台 |
| like_count |
long |
点赞数量 |
| profile_picture_url |
string |
头像 URL |
| source_advertiser_id |
string |
源广告主 ID |
| source_advertiser_link |
string |
源广告主链接 |
| user_blocked |
long |
用户是否屏蔽 (1:是 2:否) |
产品信息对象字段 (products)
| 字段名称 |
类型 |
描述 |
| id |
string |
产品 ID |
| name |
string |
产品名称 |
| ad_count |
long |
产品广告数量 |
| category_id |
string |
分类 ID |
| category_name |
string |
分类名称 |
| creation_time |
long |
创建时间 |
| currency |
string |
货币类型 |
| image_url |
string |
产品图片 URL |
| price |
double |
产品价格 |
| price_usd |
double |
产品美元价格 |
| source_product_link |
string |
源产品链接 |
店铺信息对象字段 (store)
| 字段名称 |
类型 |
描述 |
| id |
string |
店铺 ID |
| name |
string |
店铺名称 |
| ad_count |
long |
店铺广告数量 |
| categories |
array |
店铺分类列表 |
| e_commerce_platform |
string |
电商平台 |
| e_commerce_types |
array |
电商类型列表 |
| logo_url |
string |
店铺 Logo URL |
| source_store_link |
string |
源店铺链接 |
店铺分类对象字段 (categories)
| 字段名称 |
类型 |
描述 |
| id |
string |
分类 ID |
| name_en |
string |
分类英文名称 |
| name_zh |
string |
分类中文名称 |
视频信息对象字段 (videos)
| 字段名称 |
类型 |
描述 |
| url |
string |
视频 URL |
| cover_url |
string |
封面 URL |
| duration |
long |
视频时长(秒) |
| width |
long |
视频宽度 |
| height |
long |
视频高度 |
图片信息对象字段 (images)
| 字段名称 |
类型 |
描述 |
| url |
string |
图片 URL |
| width |
long |
图片宽度 |
| height |
long |
图片高度 |
轮播图信息对象字段 (cards)
| 字段名称 |
类型 |
描述 |
| url |
string |
媒体 URL |
| cover_url |
string |
封面 URL |
| duration |
long |
时长(视频) |
| width |
long |
宽度 |
| height |
long |
高度 |
| media_type |
long |
媒体类型 (1:视频 2:图片) |
响应示例
{
"code": 200,
"message": "success",
"data": {
"ads_history": {
"ad_cost": {
"timeline": [
{
"count": 0.0,
"date": "2025-06-04"
},
{
"count": 0.0,
"date": "2025-06-05"
}
]
},
"adset_count": {
"timeline": [
{
"count": 1.0,
"date": "2025-06-04"
},
{
"count": 1.0,
"date": "2025-06-05"
}
]
}
},
"advertisement": {
"id": "9a4566becbe35c6f6c0f1beac8dd6e30",
"active_days": 1,
"ad_caption": "ladyluxve.com",
"ad_content": "🚨 ALERTA TENDENCIA 🚨\nEl botín que está arrasando en redes sociales ya llegó a Venezuela 🇻🇪",
"ad_forecast": 1,
"ad_link": "https://www.facebook.com/ads/library/?id=1124613119690978",
"ad_link_description": "⭐⭐⭐⭐⭐",
"ad_platform": [
"FACEBOOK",
"INSTAGRAM",
"AUDIENCE_NETWORK",
"MESSENGER",
"THREADS"
],
"ad_started_at": 1749020400,
"ad_status": 3,
"ad_title": "35% OFF Hoy+ Envio GRATIS",
"adset_count": 1,
"advertiser": {
"id": "7302fd79a2d742bb6c0f1beac8dd6e30",
"name": "Lady Lux",
"ad_count": 11,
"ad_country": ["other"],
"ads_library_link": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=ALL&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=685400174653320",
"adset_count": 11,
"e_commerce_platform": "shopify",
"like_count": 1201,
"profile_picture_url": "https://fb-cdn.pipispy.com/images/38f38e24fa774ca1bf01da9aba9ac47e.png",
"source_advertiser_id": "685400174653320",
"source_advertiser_link": "https://facebook.com/61576957564176",
"user_blocked": 2
},
"button_text": "Shop now",
"button_type": "SHOP_NOW",
"cards": [],
"country": ["other"],
"first_discovered_at": 1749024028,
"images": [],
"landing_page_type": 1,
"landing_pages": [
"https://ladyluxve.com/products/botin%E2%84%A2-starway"
],
"language": "es",
"last_discovered_at": 1749108995,
"latest_actived_at": 1749106800,
"media_format": 1,
"products": [
{
"currency": "USD",
"id": "dd66f501d1faa6adbe16801b708c35d5",
"name": "Botin™ - Starway",
"price": 49.99,
"ad_count": 3,
"creation_time": 1748732926,
"image_url": "https://fb-cdn.pipispy.com/images/pimg_85d72df090674a0b56a4f.png",
"price_usd": 49.99,
"source_product_link": "https://ladyluxve.com/products/botin%E2%84%A2-starway"
}
],
"source_ad_id": "1124613119690978",
"store": {
"categories": [
{
"id": "62739ba938365b2f72048eca",
"name_en": "Shoes",
"name_zh": "鞋类"
}
],
"id": "389f77b24aefc6ffbe16801b708c35d5",
"name": "Lady lux",
"ad_count": 11,
"e_commerce_platform": "shopify",
"logo_url": "http://ladyluxve.com/cdn/shop/files/ladyancho.jpg?crop=center&height=32&v=1748537443&width=32",
"source_store_link": "https://ladyluxve.com"
},
"user_collected": 2,
"videos": [
{
"duration": 16,
"height": 1280,
"url": "https://fb-cdn.pipispy.com/videos/a98e21abd3b3b2340f9998d5a8f209ac.mp4",
"width": 720,
"cover_url": "https://fb-cdn.pipispy.com/images/40960e1f77f4077634bf463593b629ba.png"
}
],
"size": "9:16",
"clarity": "FHD",
"aspect_ratio": "720x1280"
}
},
"version": "v1",
"timestamp": null,
"sign": null,
"remaining_credits": 9980,
"consumed_credits": 1,
"success": true,
"fail": false
}
错误码
| 错误码 |
描述 |
| 400 |
请求错误 - 参数无效 |
| 401 |
未授权 - API 密钥无效 |
| 500 |
服务器内部错误 |
注意事项
- 广告 ID 必须是有效的系统内部 ID
- 响应中的 URL 已转换为 CDN 地址
- 所有时间戳均为 Unix 时间戳(秒)
- AI 分析字段仅在视频广告中返回
- 部分字段可能为空,取决于广告类型和数据完整性