Facebook Ad Transcript
Facebook Ad Transcript 是与 Ad Library 目标关联的口播记录，包含来源 URL、文本、语言、格式、采集时间和可选 shortcode 上下文。这些记录可用于广告信息审阅、关键词索引、按语言处理和来源可追溯归档。
主要特性
- 批量提交 Ad Library URL接收受支持 Facebook 主机上的 Ad Library URL，并将每个去重后的 URL 作为独立字幕目标处理。
- 关联来源的口播文本返回非空口播文本及其提交来源 URL；来源 ID 缺失时，记录 ID 会回退为该 URL。
- 语言与格式上下文标准化记录包含可空的来源语言、plaintext 或 WebVTT 格式、采集时间和可选 shortcode。
- 仅保存可用记录只有所选广告目标返回非空口播内容时才保存结果，因此成功任务的记录数可能少于提交的 URL 数。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
urls | 必填 | 受支持 Facebook 主机上的 Ad Library URL，使用逗号或换行分隔；每条路径都必须包含 /ads/library。 |
如何使用
提交 Facebook Ad Library URL；由于只有非空口播文本会生成结果，还需要按来源 URL 对账。
- 准备一个或多个 Facebook Ad Library URL；主机必须是 facebook.com、www.facebook.com 或 m.facebook.com，路径中必须包含 /ads/library。
- 向 /v1/facebook/ad-transcript POST urls，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或失败。
- 读取 data.results.items；当 results.has_more 为 true 时，使用 results.next_cursor 请求下一页。
curl -X POST "https://api.socq.ai/v1/facebook/ad-transcript" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.facebook.com/ads/library/?id=123456789012345"]}'
# 轮询 GET /v1/tasks/{task_id}
# 使用 GET /v1/tasks/{task_id}?limit=50&cursor={next_cursor} 继续读取最佳使用场景
- 广告信息审阅： 利用关联来源的口播文本，比较一组选定公开广告目标使用的口头表达。
- 广告语音检索索引： 将文本与记录 ID、来源 URL、采集时间和 shortcode 上下文一起建立索引，使已知广告字幕可按口播词检索。
- 字幕处理路由： 利用语言和格式字段，将 plaintext 与 WebVTT 记录分配到相应的文本、字幕或语言处理流程。
使用建议
- 每条 URL 都应使用受支持的 Facebook 主机并保留 /ads/library 路径；其它主机或路径无法通过请求校验。
- 同一 Ad Library 目标带有不同查询参数时，批量提交前先规范化 URL，因为采集器只移除字符串完全相同的重复项。
- 任务成功后将返回的 url 与输入列表对照，使不受支持或没有非空口播内容的广告仍可在业务流程中追踪。
- 根据 format 选择解析方式，并将 language 与 extra.shortcode 作为可空值处理；created_at 是预留字段，当前固定返回 null。
- 大量 URL 跨越请求的结果页上限时，只要 results.has_more 为 true，就继续传递 results.next_cursor。
相关 API
需要其他类型的 Facebook 公开数据时，可以使用以下 API。
- Facebook Pages API — 获取公开 Page 资料、联系方式、图片和可见受众评分。
- Facebook Posts API — 从受支持的 Facebook URL 采集公开帖子、媒体、表情回应、评论数和分享数。
- Facebook Comments API — 从帖子 URL 采集公开评论、作者、互动、媒体和来源链接。
- Facebook Video Transcript API — 从已知的公开视频帖子或 Reel URL 提取可用字幕文本和格式。
- Facebook Group Posts API — 从 Facebook 群组 URL 采集公开帖子，可选择排序并设置每个群组的数量上限，返回作者、视频媒体和可见互动信息。
- Facebook Events Search API — 按关键词搜索公开活动，返回日程、地点、出席指标、封面媒体和活动状态字段。
- Facebook Comment Replies API — 使用已知评论的 feedback ID 和 expansion token 获取公开回复，返回文本、作者标识、互动指标和父级上下文。
- Facebook Company Reviews API — 采集公开 Page 评价，返回评价文本、评价者链接、评分、点赞数、时间和公司上下文。
- Facebook Event Details API — 通过已知公开活动 URL 采集标准化元数据、日程、地点、媒体和可见互动指标。
- Facebook Profile Events API — 从个人资料或 Page URL 采集关联的公开活动，返回名称、日程、地点、媒体、可见指标和来源上下文。
- Facebook Profile Photos API — 从个人资料或 Page URL 采集公开照片，返回说明文字、作者上下文、互动指标、图片元数据和来源引用。
- Facebook Profiles API — 通过已知 Facebook URL 查询公开个人资料或主页，返回身份信息、简介、头像、可见计数和输入上下文。
- Facebook Reels API — 从个人资料或 Page URL 采集公开 Reels，返回说明文字、作者上下文、视频元数据、可见互动和来源引用。