[中文]

用途:

• 获取视频的字幕列表或指定语言的字幕内容
• 支持多种字幕格式输出

参数:

• video_id: 视频ID（推荐）
• video_url: 完整的视频URL（可选）
• language_code: 语言代码（如 en, zh-Hans, a.en），为空时返回可用字幕列表
• format: 字幕格式
  • srt: SubRip 字幕格式（带时间轴）
  • xml: 原始 XML 格式
  • json3: JSON 格式（YouTube 原始结构）
  • txt: 纯文本（无时间轴）

使用流程:

1. 不传 language_code，获取字幕列表
2. 从列表中选择 language_code，获取字幕内容

返回数据:

不传 language_code 时（字幕语言列表）:

{
  "video_id": "dQw4w9WgXcQ",
  "captions": [
    { "language_code": "en", "language_name": "English" },
    { "language_code": "ja", "language_name": "Japanese" }
  ]
}

传 language_code 时（字幕内容）:

• format=srt: 标准 SRT 字幕文件内容（含序号、时间轴、文本）
• format=txt: 纯文本（仅文字，无时间轴）
• format=xml: YouTube 原始 XML 字幕
• format=json3: YouTube JSON 格式字幕

视频较大时（转异步任务）:

{
  "video_id": "dQw4w9WgXcQ",
  "status": "processing",
  "job_id": "123e4567-e89b-12d3-a456-426614174000"
}

• 返回 status="processing" 时，用 job_id 调用 /get_video_captions_result 取最终字幕

视频无字幕时:

{
  "video_id": "dQw4w9WgXcQ",
  "captions": [],
  "message": "No transcript is available for this video",
  "message_zh": "该视频没有可用字幕"
}

注意事项:

• 并非所有视频都有字幕
• 仅返回视频本身已有的字幕，不提供 AI 语音转写生成；视频没有字幕时直接返回上述无字幕结果
• video_id 和 video_url 至少提供一个
• 大视频会转为异步任务，需配合 /get_video_captions_result 轮询获取结果
• 视频无字幕时返回 200 + 上述提示，且照常计费（上游已对该请求计费）

价格:

• $0.008 USD / 请求

[English]

Purpose:

• Get video caption list or caption content for a specific language
• Supports multiple caption format outputs

Parameters:

• video_id: Video ID (recommended)
• video_url: Full video URL (optional)
• language_code: Language code (e.g. en, zh-Hans, a.en), returns available caption list if empty
• format: Caption format
  • srt: SubRip subtitle format (with timestamps)
  • xml: Raw XML format
  • json3: JSON format (YouTube raw structure)
  • txt: Plain text (no timestamps)

Returns:

Without language_code (caption language list):

{
  "video_id": "dQw4w9WgXcQ",
  "captions": [
    { "language_code": "en", "language_name": "English" },
    { "language_code": "ja", "language_name": "Japanese" }
  ]
}

With language_code (caption content):

• format=srt: Standard SRT subtitle content (with sequence numbers, timestamps, text)
• format=txt: Plain text (text only, no timestamps)
• format=xml: YouTube raw XML captions
• format=json3: YouTube JSON format captions

Large videos (async job):

{
  "video_id": "dQw4w9WgXcQ",
  "status": "processing",
  "job_id": "123e4567-e89b-12d3-a456-426614174000"
}

• When status="processing" is returned, poll /get_video_captions_result with the job_id to retrieve the final captions

Video has no captions:

{
  "video_id": "dQw4w9WgXcQ",
  "captions": [],
  "message": "No transcript is available for this video",
  "message_zh": "该视频没有可用字幕"
}

Usage flow:

1. Call without language_code to get available caption list
2. Select language_code from the list to get caption content

Notes:

• Not all videos have captions
• Only captions that already exist on the video are returned; AI speech-to-text transcription is not provided. Videos without captions return the no-captions result shown above
• At least one of video_id or video_url is required
• Large videos become async jobs; poll /get_video_captions_result for the result
• A video with no captions returns 200 with the message above and is still billed (the upstream provider charges for this request)

Price:

• $0.008 USD / request

[示例/Example]

Step 1 - 获取字幕列表: GET /get_video_captions?video_id=dQw4w9WgXcQ

Step 2 - 获取字幕内容: GET /get_video_captions?video_id=dQw4w9WgXcQ&language_code=en&format=srt