YouTube 字幕 API

通过一次带认证的 GET 请求读取公开视频已有字幕，返回完整文本、语言和带时间戳的 JSON 分段，方便接入你的应用。

单一 REST 端点
结构化 JSON 输出
带时间戳字幕分段
指定首选语言
幂等安全重试
明确字幕可用性

请求示例

curl "https://api.agentbody.io/v1/youtube/transcript?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ&language=en" \
  -H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>"

响应示例

来自 OpenAPI 规范的已文档化响应。

Existing captions or explicitly requested audio transcription.

{
  "caption_type": "manual",
  "language": "example_value",
  "segments": [],
  "text": "example_value",
  "video_id": "example_value"
}

功能特点

通过 YouTube 字幕 API 读取公开视频已有字幕，并以结构化 JSON 接入研究流水线、视频搜索、检索增强和内容分析产品。

单一 REST 端点

使用 Bearer API key 和公开视频 URL 调用 GET /v1/youtube/transcript。YouTube 字幕 API 通过明确的 HTTP 请求返回已有字幕轨道，无需维护浏览器自动化流程或额外客户端 SDK，即可为应用增加字幕读取能力。

结构化 JSON 输出

响应包含 caption_type、language、video_id、完整字幕文本和带时间戳的 segments。该 JSON 结构适合存储字幕、建立文本索引、实现视频内搜索，或把字幕数据传入研究与内容分析流水线。

带时间戳字幕分段

每段字幕都包含文本、开始时间和结束时间。你可以借助时间戳把搜索结果、引用、笔记或生成内容准确关联回公开视频中的对应位置，而不是只把字幕当作无法定位的大段纯文本。

指定首选语言

传入可选 language 参数，即可请求首选的公开字幕语言，例如 en 或 zh。API 只读取该视频可用的字幕轨道，不会翻译字幕，也不会创建视频未公开提供的语言轨道。

幂等安全重试

当应用需要处理重试时，可发送幂等键。同一个键的重复请求会重放已存响应，而不会创建新的计费执行，帮助后台任务和 Webhook 在网络结果不确定时恢复，避免重复处理。

明确字幕可用性

当公开视频没有可用字幕轨道时，获取 YouTube 字幕的 API 会返回 422，而不是编造文本。请将其视为该 URL 的最终可用性结果，改选其他资源，或在获得批准后使用单独计费的备用转写流程。

使用步骤

按以下六步调用 YouTube 字幕 API：选择公开视频和可用语言，并在自己的应用中处理包含时间戳分段的字幕 JSON。

创建 API Key

创建 AgentBody 账号并在控制台生成 API key。将 key 保存在服务器环境变量或获批准的密钥存储中，再作为 Bearer token 发起请求。不要把有效 key 放进浏览器代码、公开仓库或客户端构建产物中。

选择公开视频

选择需要读取已有字幕的确切公开 YouTube 视频，复制完整 URL 并确认可访问。私密、不可用或没有字幕的视频无法返回转录文本；若业务需要覆盖这类情况，请预先准备替代公开资源。

构建 GET 请求

向 /v1/youtube/transcript 发送带认证的 GET 请求，并传入 url 查询参数。本页提供 curl、JavaScript、Python、Java 和 Go 的请求示例，可直接采用与你服务一致的语言和 HTTP 客户端。

选择字幕语言

需要首选字幕语言时，传入可选 language 参数，使用 en 或 zh 等 BCP 47 标签。请求只能返回该公开视频已有的字幕轨道，不能返回新翻译轨道或视频未提供的语言。

解析 JSON 响应

在应用中读取返回的 language、完整 text 和 segments。若需要可核对的引用、带时间戳的搜索结果、学习笔记或 RAG 上下文，请保留分段时间信息，并只存储产品真正需要的字段。

正确处理 422

若 API 返回 422，说明视频没有可用的公开字幕轨道。不要对未变化的 URL 重试，因为这不是暂时性失败。请改选其他公开资源，或在调用单独计费的转写工作流前获得明确批准。

常见问题

什么是 YouTube 字幕 API？

YouTube 字幕 API 是一个带认证的 GET 端点，用于从 YouTube 视频读取已有的公开字幕轨道。传入公开视频 URL，并可选指定首选语言。成功响应会以 JSON 返回字幕元数据、完整文本和带时间戳的分段，方便应用用于搜索、研究、笔记或视频理解工作流。

可以通过 API 获取 YouTube 视频的字幕吗？

可以。向 GET /v1/youtube/transcript 发送携带 Bearer 认证的公开视频 URL 请求即可。存在公开字幕轨道时，API 会返回结构化 JSON；它不会为没有公开字幕的视频生成文本。遇到 422 时，请改选其他资源，不要对同一 URL 无变化重试。

YouTube 字幕 API 可以获取其他语言的字幕吗？

可以。使用可选 language 查询参数并传入 en 或 zh 等 BCP 47 标签，即可请求首选字幕语言。YouTube 字幕 API 只能返回该视频实际公开的字幕轨道，不会翻译字幕，也不会生成源视频没有提供的语言版本。

youtube-transcript-api 返回哪些数据？

成功的 youtube-transcript-api 响应包含 caption_type、language、video_id、完整字幕文本和带时间戳的 segments。分段时间能让应用把提取的文本对应到原视频的具体位置。你可以直接将 JSON 字段用于存储、搜索、研究或分析，无需依赖浏览器渲染的字幕页面。

如何处理 youtube_transcript_api 错误？

400 表示需要修正请求，401 表示需要配置有效 API key。422 表示该视频没有可用公开字幕轨道，不应对同一 URL 原样重试。对于临时性的 502、503 或 504 错误，可使用退避策略重试；若仍失败，请报告临时不可用状态。

幂等重试会产生第二次扣费吗？

不会。当应用可能因网络中断重试时，请附带幂等键。同一个键会重放已存响应，而不会再次执行相同请求。这让 youtubetranscriptapi 集成拥有可控的重试路径，并保留原结果，避免重复计费处理。