YouTube Transcripts API

YouTube Transcripts

主要特性

• 多视频字幕获取一个请求可以获取多个公开视频的可用字幕文本。
• 首选语言选择使用 en 或 zh-CN 等有效 BCP-47 code 请求首选语言。
• 可用语言信息同时返回实际选中的语言和可用字幕语言列表。
• 纯文本字幕格式统一输出 plaintext，并在已知时返回字幕来源信息。
• 可追溯的视频上下文每条字幕关联视频 ID、标题、频道信息、发布时间、时长和 collected_at。

参数

如何使用

先筛出真正需要处理的视频，再请求字幕。文本进入搜索、RAG、摘要、翻译或合规流程前，务必确认实际返回语言与字幕来源。

1. 选择公开视频 URL，最好先通过发现或详情审核排除无关内容。
2. 向 /v1/youtube/transcripts POST urls 和可选 BCP-47 language，并保存 task_id。
3. 轮询 /v1/tasks/{task_id}；即使任务成功，结果数也可能少于提交 URL 数。
4. 逐条检查 language、available_languages 与 transcript_source，再切分纯文本；has_more 为 true 时继续翻页。

curl -X POST "https://api.socq.ai/v1/youtube/transcripts" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.youtube.com/watch?v=arj7oStGLkU"],"language":"en"}'

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

最佳使用场景

• 视频摘要： 使用可用字幕文本为长视频生成摘要、研究笔记或内容简报。
• 可搜索视频档案： 把字幕文本与视频 ID、标题、频道信息和语言元数据一起建立索引。
• 主题与信息提取： 从指定公开视频集合中识别主题、实体、观点和关键词。
• 翻译与本地化： 根据实际语言和可用语言字段，把字幕文本分发到翻译流程。

使用建议

• 下游分流必须使用返回的 language，而不是请求偏好；回退到其他可用轨道属于正常结果。
• 自动生成字幕可能错误识别人名、标点和专业术语。保留 transcript_source，高风险内容必须对照原视频。
• 成功任务结果较少通常表示部分视频没有可用公开字幕，不等于整个批次失败。
• plaintext 不包含分段时间戳或说话人标签，不应从响应中编造精确引用时间或发言人。
• 文本可以在下游切分，但每个片段都应保留视频 ID、语言、来源与 collected_at，确保引用可追溯。
• 字幕需要进入可搜索目录时，可用 Videos 补齐标题、媒体与公开指标。
• 如果业务必须精确覆盖某种语言，应先检查 available_languages，并把回退结果交给人工复核。

相关 API