Facebook Ad Transcript API

Facebook Ad Transcript

主要特性

• 批量提交 Ad Library URL接收受支持 Facebook 主机上的 Ad Library URL，并将每个去重后的 URL 作为独立字幕目标处理。
• 关联来源的口播文本返回非空口播文本及其提交来源 URL；来源 ID 缺失时，记录 ID 会回退为该 URL。
• 语言与格式上下文标准化记录包含可空的来源语言、plaintext 或 WebVTT 格式、采集时间和可选 shortcode。
• 仅保存可用记录只有所选广告目标返回非空口播内容时才保存结果，因此成功任务的记录数可能少于提交的 URL 数。

参数

如何使用

提交 Facebook Ad Library URL；由于只有非空口播文本会生成结果，还需要按来源 URL 对账。

1. 准备一个或多个 Facebook Ad Library URL；主机必须是 facebook.com、www.facebook.com 或 m.facebook.com，路径中必须包含 /ads/library。
2. 向 /v1/facebook/ad-transcript POST urls，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或失败。
4. 读取 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