如何通过 API 批量下载 YouTube 字幕

手动下载一条 YouTube 字幕并不难；真正困难的是稳定处理成百上千个公开视频。视频可能没有字幕、目标语言可能不存在、自动字幕可能包含识别错误，而且每条结果都必须能够追溯到原视频。

本指南介绍如何使用 SocQ YouTube Transcripts API 获取公开视频已有的字幕文本，通过异步任务处理多个视频 URL，并把标准化结果用于搜索、摘要、研究或 RAG。

**快速结论：**向 POST /v1/youtube/transcripts 提交公开视频 URL 和可选的 BCP-47 语言代码，保存返回的 task_id，轮询任务接口，再从 data.results.items 读取结果。SocQ 获取的是已有可用字幕，不会在字幕缺失时悄悄生成新的语音转写。

官方 YouTube API 能下载任意公开视频字幕吗？

不能。YouTube Data API 提供 caption 资源，但 captions.download 面向有权管理对应视频字幕的用户。它要求 OAuth 授权，并要求当前用户有编辑视频的权限；每次调用还消耗 200 个配额单位。

因此应区分三类需求：

SocQ 解决第二类问题。官方限制请参考 Google 的 caption 下载文档。

提交字幕获取任务

接口接受一个或多个公开视频 URL，也可以指定 en、zh-CN 等首选语言：

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"
  }'

提交后会创建异步任务。不要因为没有立即返回字幕就重复提交同一批 URL，而应保存 task_id 并轮询：

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

queued 和 running 是正常中间状态。任务成功后，从 data.results.items 读取记录；若 has_more 为 true，使用 next_cursor 获取下一页。

理解标准化字幕响应

典型记录如下：

{
  "id": "arj7oStGLkU",
  "platform": "youtube",
  "resource": "transcripts",
  "type": "transcript",
  "url": "https://www.youtube.com/watch?v=arj7oStGLkU",
  "title": "Inside the Mind of a Master Procrastinator",
  "text": "可供处理的纯文本字幕。",
  "language": "en",
  "available_languages": ["en"],
  "format": "plaintext",
  "transcript_source": "auto_generated",
  "author": {
    "username": "TED",
    "name": "TED"
  },
  "created_at": "2016-04-06T00:00:00",
  "collected_at": "2026-07-16T08:00:00Z",
  "extra": {
    "duration_seconds": 843
  }
}

下游处理最重要的字段包括：

• text：选中的纯文本字幕。
• language：实际返回的语言，不一定与请求偏好完全相同。
• available_languages：视频可用的字幕语言。
• transcript_source：已知时标记人工或自动生成来源。
• id、url、title、author：用于溯源。
• created_at 和 collected_at：区分发布时间与采集时间。

当前响应是纯文本，不包含可靠的逐句时间戳或说话人标签。不要把它伪装成精确 SRT，也不要为引用虚构时间点。

正确处理字幕语言

请求语言是偏好，不是保证。生产流程必须根据返回的 language 做判断：

1. 可能返回完全匹配的语言。
2. 可能返回兼容的基础语言。
3. 可能回退到其他可用语言。
4. 没有可用公开字幕时可能不生成记录。

将 language 与 available_languages 和正文一起保存。若业务必须使用指定语言，就把回退结果送入审核或翻译流程，而不是直接进入搜索索引或大模型。

自动字幕同样需要质量控制。背景噪音、口音、多人重叠说话、专有名词和多语言切换都会降低准确率。可参考 YouTube 的自动字幕说明。

批量处理 YouTube 字幕

批量任务应按数据管道设计：

视频 URL
   ↓
格式校验与去重
   ↓
分批提交异步任务
   ↓
带退避的任务轮询
   ↓
语言与质量检查
   ↓
分段、索引或摘要

建议：

• 提交前统一 youtu.be、youtube.com/watch 等 URL，并按视频 ID 去重。
• 保存任务 ID、批次 ID 和原始输入，方便排错。
• 对轮询使用指数退避和随机抖动。
• 将“不存在字幕”和“任务失败”分开记录。
• 用视频 ID 作为幂等键，避免重复入库。
• 保留来源 URL 和采集时间，支持后续刷新与删除。

Python 批量处理示例

import time
import requests

BASE_URL = "https://api.socq.ai/v1"
HEADERS = {
    "Authorization": f"Bearer {SOCQ_API_KEY}",
    "Content-Type": "application/json",
}

submit = requests.post(
    f"{BASE_URL}/youtube/transcripts",
    headers=HEADERS,
    json={"urls": video_urls, "language": "zh-CN"},
    timeout=30,
)
submit.raise_for_status()
task_id = submit.json()["data"]["task_id"]

delay = 2
while True:
    response = requests.get(
        f"{BASE_URL}/tasks/{task_id}",
        headers=HEADERS,
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()["data"]

    if task["status"] == "succeeded":
        items = task["results"]["items"]
        break
    if task["status"] in {"failed", "cancelled"}:
        raise RuntimeError(task)

    time.sleep(delay)
    delay = min(delay * 1.5, 15)

实际代码还应处理游标分页、429、5xx、网络超时与可重试任务错误。

如何把字幕用于 RAG

不要把整段长字幕直接作为一个向量。更稳妥的流程是：

1. 保留视频和字幕的原始记录。
2. 按语义或固定长度分块，并设置少量重叠。
3. 每个分块保存 video_id、URL、标题、语言和来源。
4. 过滤过短、重复或明显低质量文本。
5. 为分块生成向量并写入索引。
6. 回答时返回原视频链接，并明确字幕可能来自自动识别。

由于响应没有可靠逐句时间戳，引用应指向视频，而不是声称某句话位于精确秒数。

错误与空结果处理

常见情况包括：

不要把空结果转换成空字符串字幕。空字符串容易被误判为有效文档，污染搜索与分析。

合规与内容使用

字幕可公开获取并不代表可任意再发布或训练模型。应：

• 只处理业务确实需要的公开视频。
• 保留来源和作者信息。
• 遵守 YouTube 条款、版权与隐私要求。
• 为删除和权利人请求准备下线机制。
• 对大规模再分发、商业训练或敏感分析进行法律审查。

SocQ 提供技术访问能力，不授予内容版权或额外使用许可。

YouTube 字幕 API 常见问题（FAQ）

SocQ 会在没有字幕时自动转写音频吗？

不会。SocQ 获取已有的公开字幕。没有字幕时，应使用独立的语音转文字服务。

可以指定中文字幕吗？

可以提交 zh-CN 等 BCP-47 语言偏好，但实际结果取决于视频可用字幕。始终检查返回的 language。

返回逐句时间戳吗？

当前返回纯文本，不提供可靠逐句时间戳或说话人标签。

可以一次提交多个视频吗？

可以。接口接受多个公开视频 URL，并通过异步任务处理。

如何避免重复计费或重复任务？

在提交前按视频 ID 去重，保存 task_id，任务运行期间不要重复提交同一批次。

官方 YouTube API 为什么不适合任意公开视频字幕？

captions.download 需要 OAuth，且调用用户必须有权编辑对应视频，因此更适合管理自己拥有的内容。