跳转到正文
中文
获取 API 密钥

YouTube 数据 / JavaScript

使用 JavaScript 获取 YouTube 字幕

获取现有字幕轨道,保存文本,并保留时间戳,以便搜索、引用和视频跳转。

FlashData · 发布于

按带时间戳的转录片段排列的视频字幕

准备环境

使用 Node.js 22 或更高版本。脚本使用内置的 fetch 和文件 API,因此无需安装任何包。你需要 API 密钥、可用积分,以及已有字幕轨道的视频 ID。

bash
# Replace YOUR_API_KEY near the top of the code below.
export YOUTUBE_VIDEO_ID='dQw4w9WgXcQ'

视频 ID 是 v 值,位于 YouTube 观看 URL 中。对于此端点,通过以下字段传入 ID: video_id.

获取并保存字幕

将代码保存为 transcript.mjs。它请求英文自动字幕轨道,将纯文本写入一个文件,并在另一个文件中保留完整的字幕对象。

javascript
import { writeFile } from "node:fs/promises";

const apiKey = "YOUR_API_KEY";
const videoId = process.env.YOUTUBE_VIDEO_ID;
if (!videoId) {
  throw new Error("Set YOUTUBE_VIDEO_ID first.");
}
const baseUrl = "https://data.flashdata.dev";
const response = await fetch(baseUrl + "/v1/queries/realtime", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": apiKey,
  },
  body: JSON.stringify({
    source: "youtube_transcript",
    video_id: videoId,
    params: { language: "en", auto: true },
  }),
  signal: AbortSignal.timeout(60000),
});

const payload = await response.json();
if (!response.ok || payload.error) {
  throw new Error(payload.message ?? payload.detail ?? "Transcript request failed");
}
const transcript = payload.results?.[0];
if (!Array.isArray(transcript?.segments) || transcript.segments.length === 0) {
  throw new Error("No caption segments were returned for this video and language.");
}

const text = transcript.segments.map(segment => segment.text).join("\n");
await writeFile("transcript.txt", text, "utf8");
await writeFile("transcript.json", JSON.stringify(transcript, null, 2), "utf8");
console.log("Saved transcript.txt and transcript.json (with segment timestamps).");
bash
node transcript.mjs

transcript.txt 便于阅读或进一步处理文本。 transcript.json 保留语言信息和分段时间戳。

保留时间戳

字幕分段包含 start, end 和 text 字段。构建搜索索引时,为每个分块保留视频 ID、语言和时间戳,以便匹配结果能够指向原视频。

json
{
  "source": "youtube_transcript",
  "status": "done",
  "results": [
    {
      "videoId": "dQw4w9WgXcQ",
      "languageCode": "en",
      "languageName": null,
      "isAutoGenerated": true,
      "segments": [
        {
          "start": 0.32,
          "end": 14.58,
          "text": "[Music]"
        },
        {
          "start": 18.8,
          "end": 25.96,
          "text": "We're no strangers to"
        },
        {
          "start": 21.8,
          "end": 29.119,
          "text": "love. You know the rules and so do"
        },
        {
          "start": 25.96,
          "end": 30.279,
          "text": "I. I feel commitments from what I'm"
        },
        {
          "start": 29.119,
          "end": 34.36,
          "text": "thinking"
        },
        {
          "start": 30.279,
          "end": 39.559,
          "text": "of. You wouldn't get this from any other"
        },
        {
          "start": 34.36,
          "end": 43.12,
          "text": "guy. I just want to tell you how I'm"
        },
        {
          "start": 39.559,
          "end": 45.84,
          "text": "feeling. Got to make you understand."
        },
        {
          "start": 43.12,
          "end": 49.2,
          "text": "Never going to give you up. I'm going to"
        },
        {
          "start": 45.84,
          "end": 53.32000000000001,
          "text": "let you down. I'm going to run around"
        },
        {
          "start": 49.2,
          "end": 56.399,
          "text": "and desert you. I'm going to make"
        },
        {
          "start": 53.32,
          "end": 59.879,
          "text": "you say goodbye."
        },
        {
          "start": 56.399,
          "end": 64.04,
          "text": "Tell a lie and hurt"
        },
        {
          "start": 59.879,
          "end": 67.2,
          "text": "you. We've known each other for so"
        },
        {
          "start": 64.04,
          "end": 70.56,
          "text": "long. Your heart's been aching, but"
        },
        {
          "start": 67.2,
          "end": 72.60000000000001,
          "text": "you're too shy to say we don't know"
        },
        {
          "start": 70.56,
          "end": 77.799,
          "text": "what's been going"
        },
        {
          "start": 72.6,
          "end": 81.479,
          "text": "on. We know the game and we're going to"
        },
        {
          "start": 77.799,
          "end": 84.56,
          "text": "play. If you ask me how I'm"
        },
        {
          "start": 81.479,
          "end": 88.32,
          "text": "feeling, don't tell me your truth. to"
        },
        {
          "start": 84.56,
          "end": 88.32000000000001,
          "text": "see. I will give"
        },
        {
          "start": 89.88,
          "end": 94.72,
          "text": "you"
        },
        {
          "start": 91.72,
          "end": 94.72,
          "text": "around"
        },
        {
          "start": 95,
          "end": 99.04,
          "text": "you. I will say"
        },
        {
          "start": 99.56,
          "end": 106.759,
          "text": "goodbye and hurt you. I will give"
        },
        {
          "start": 103.99,
          "end": 108.6,
          "text": "[Music]"
        },
        {
          "start": 106.759,
          "end": 115.92,
          "text": "you"
        },
        {
          "start": 108.6,
          "end": 115.92,
          "text": "around you. I will leave you. I will say"
        },
        {
          "start": 116.439,
          "end": 121.079,
          "text": "goodbye and hurt you."
        },
        {
          "start": 128.319,
          "end": 132.56,
          "text": "Never going to give. Never going to"
        },
        {
          "start": 129.759,
          "end": 134,
          "text": "give."
        },
        {
          "start": 132.56,
          "end": 136.8,
          "text": "Never going to give. Never going to"
        },
        {
          "start": 134,
          "end": 141.04,
          "text": "give."
        },
        {
          "start": 136.8,
          "end": 143.68,
          "text": "We've known each other for so long."
        },
        {
          "start": 141.04,
          "end": 147.51999999999998,
          "text": "Your heart's been aching, but you're too"
        },
        {
          "start": 143.68,
          "end": 148.52,
          "text": "shy to say it. We both know what's been"
        },
        {
          "start": 147.52,
          "end": 152.239,
          "text": "going"
        },
        {
          "start": 148.52,
          "end": 157.8,
          "text": "on. We know the game and we're going to"
        },
        {
          "start": 152.239,
          "end": 161.36,
          "text": "play it. I just want to tell you how I'm"
        },
        {
          "start": 157.8,
          "end": 163.92000000000002,
          "text": "feeling. Got to make you understand."
        },
        {
          "start": 161.36,
          "end": 166.8,
          "text": "Never going to give you up. Never going"
        },
        {
          "start": 163.92,
          "end": 171.28,
          "text": "to let you down. Never going to run"
        },
        {
          "start": 166.8,
          "end": 171.28,
          "text": "around and desert you. Heat."
        },
        {
          "start": 172.33,
          "end": 182.76,
          "text": "[Music]"
        },
        {
          "start": 178.76,
          "end": 182.76,
          "text": "Heat. Heat. Heat."
        },
        {
          "start": 183.39,
          "end": 195.2,
          "text": "[Music]"
        },
        {
          "start": 191.04,
          "end": 197.76,
          "text": "Never going to tell a lie and hurt you."
        },
        {
          "start": 195.2,
          "end": 200.64,
          "text": "Never going to give you up. Never going"
        },
        {
          "start": 197.76,
          "end": 204.239,
          "text": "to let you down. Never going to run"
        },
        {
          "start": 200.64,
          "end": 206.83999999999995,
          "text": "around and desert you. Never going to"
        },
        {
          "start": 204.239,
          "end": 211.879,
          "text": "make you cry. Never going to say"
        },
        {
          "start": 206.84,
          "end": 211.879,
          "text": "goodbye. Never going to say goodbye."
        }
      ],
      "fullText": "[Music] We're no strangers to love. You know the rules and so do I. I feel commitments from what I'm thinking of. You wouldn't get this from any other guy. I just want to tell you how I'm feeling. Got to make you understand. Never going to give you up. I'm going to let you down. I'm going to run around and desert you. I'm going to make you say goodbye. Tell a lie and hurt you. We've known each other for so long. Your heart's been aching, but you're too shy to say we don't know what's been going on. We know the game and we're going to play. If you ask me how I'm feeling, don't tell me your truth. to see. I will give you around you. I will say goodbye and hurt you. I will give [Music] you around you. I will leave you. I will say goodbye and hurt you. Never going to give. Never going to give. Never going to give. Never going to give. We've known each other for so long. Your heart's been aching, but you're too shy to say it. We both know what's been going on. We know the game and we're going to play it. I just want to tell you how I'm feeling. Got to make you understand. Never going to give you up. Never going to let you down. Never going to run around and desert you. Heat. [Music] Heat. Heat. Heat. [Music] Never going to tell a lie and hurt you. Never going to give you up. Never going to let you down. Never going to run around and desert you. Never going to make you cry. Never going to say goodbye. Never going to say goodbye."
    }
  ],
  "usage": {
    "credits": 0.01
  },
  "created_at": "2026-09-16T07:45:44.040Z"
}

视频链接可以包含 &t=SECONDSs ,从分段起始时间附近打开视频。即使将多个分段合并到一个文档中,时间戳仍可用于引用和定位。

处理字幕缺失的情况

字幕可用性取决于视频、语言和轨道类型。轨道不可用时可能返回错误或没有可用分段;脚本会检查这两种情况,输出提示并停止。

这些端点用于获取已有字幕,不会生成新的语音转文字结果。如需创作者提供的字幕轨道,请查看 Captions API 及其选项。如果所请求的轨道不存在,请避免重复提交同一请求。