Facebook Video Transcript API

Facebook Video Transcript

主要特性

• 按已知 URL 批量提取接收公开 Facebook 视频帖子或 Reel URL 列表，并在提取字幕前移除字符串完全相同的重复项。
• 关联来源的字幕记录每条可用字幕都返回提交的来源 URL，记录 ID 缺失时也会使用该 URL 作为标识。
• 明确的文本格式将返回文本标记为 plaintext 或 WebVTT，并提供字幕采集时间，便于后续按格式处理。
• 仅保留可用结果只有提交的公开 URL 返回非空字幕文本时才创建标准化记录，因此结果数量可能少于输入数量。

参数

如何使用

提交已知的 Facebook 公开视频帖子或 Reel URL；由于只有非空字幕会生成结果，还需要按来源 URL 对账。

1. 准备一个或多个已知的公开 Facebook 视频帖子或 Reel URL；此接口不会发现 Page 的视频列表。
2. 向 /v1/facebook/video-transcript POST urls，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或失败。
4. 读取 data.results.items，在 has_more 为 true 时继续传 next_cursor，并按每条记录的 url 和 format 保存文本。

curl -X POST "https://api.socq.ai/v1/facebook/video-transcript" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.facebook.com/reel/1535656380759655"]}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 GET /v1/tasks/{task_id}?limit=50

最佳使用场景

• 语音内容检索索引： 将字幕文本与来源 URL、记录 ID、格式和采集时间一起建立索引，使选定的公开视频可按口播内容检索。
• 选定视频与 Reel 审阅： 利用关联来源的字幕文本，审阅一组已知公开视频帖子或 Reel 中的口播内容。
• 帖子元数据补全： 需要同时使用口播内容和公开帖子上下文时，可按来源 URL 将字幕文本与单独采集的帖子详情关联。

使用建议

• 提交前先确认每个目标是可访问的公开视频帖子或 Reel URL；格式错误、私密、已删除、不受支持或不可用的媒体可能不产生记录。
• 同一视频可能带有跟踪参数或不同 URL 形式时，批量提交前先做规范化，因为后端只移除字符串完全相同的重复项。
• 任务成功后将返回的 url 与输入列表对照，使没有非空字幕文本的 URL 在业务流程中仍可追踪。
• 解析文本前先读取 format；webvtt 记录可能保留 cue 标记，不能直接按无结构 plaintext 处理。
• URL 批次跨越多个结果页时，只要 results.has_more 为 true，就继续使用 results.next_cursor 读取。

相关 API