如何用 API 取得 YouTube 逐字稿（curl、Python、JavaScript）

要用 API 取得 YouTube 逐字稿，只要送出一個帶有影片 URL 或 ID 以及 API 金鑰的 HTTP 請求，再從回應中讀取逐字稿即可。本指南用 sum.video 逐字稿 API 示範 curl、Python 與 JavaScript 的請求，接著說明格式、錯誤與費用。

API 會回傳什麼

這個端點會回傳公開 YouTube 影片的現有字幕，不論是創作者自己撰寫的，還是 YouTube 自動產生的。它不會把音訊轉成文字。如果影片沒有字幕，你會收到錯誤，而不是猜測的結果（下文會再說明）。

基本資訊：

• 端點：POST https://sum.video/api/v1/transcript（GET 也可以）
• 驗證：把你的金鑰放在 X-API-Key 標頭，或使用 Authorization: Bearer <key>
• 輸入：url 或 video_id
• 選用的 lang（預設 en）
• 選用的 format：json、text 或 srt

回應會告訴你字幕軌的實際語言，以及它是否為自動產生，讓你知道該預期什麼品質。

步驟 1：建立 API 金鑰

登入後，在 API 儀表板（sum.video 上的 /dashboard/api）建立金鑰。你最多可以同時擁有 5 把啟用中的金鑰，方便把測試金鑰與正式金鑰分開。你的第一把金鑰附有 10 點免費點數，足夠 5 份逐字稿，所以下面的內容都可以免費試用。

步驟 2：送出第一個請求

curl

curl -X POST https://sum.video/api/v1/transcript \
  -H "X-API-Key: $SUMVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "lang": "en", "format": "text"}'

因為 GET 也可以使用，你甚至可以從只負責組出 URL 的腳本來測試。建議把金鑰放在標頭中送出，這樣它就不會出現在日誌裡。

Python

import os
import requests

resp = requests.post(
    "https://sum.video/api/v1/transcript",
    headers={"X-API-Key": os.environ["SUMVIDEO_API_KEY"]},
    json={"video_id": "dQw4w9WgXcQ", "lang": "en", "format": "text"},
    timeout=30,
)

if resp.status_code == 404:
    print("No captions for this video")
else:
    resp.raise_for_status()
    print(resp.text)

JavaScript（Node 18+ 或瀏覽器）

const resp = await fetch("https://sum.video/api/v1/transcript", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.SUMVIDEO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_id: "dQw4w9WgXcQ",
    lang: "en",
    format: "text",
  }),
});

if (resp.status === 404) {
  console.log("No captions for this video");
} else if (!resp.ok) {
  throw new Error(`Request failed: ${resp.status}`);
} else {
  console.log(await resp.text());
}

請把金鑰保留在伺服器端。放在瀏覽器程式碼裡的金鑰，任何打開開發人員工具的人都能複製。

步驟 3：選擇適合的格式

如果你打算連到影片的特定時刻，請使用 json，並用片段的 offset 組出連結。要餵給 LLM 的話，text 比較短也比較簡單。如果之後想手動在逐字稿裡搜尋，請參考如何搜尋 YouTube 影片的逐字稿。

步驟 4：選擇語言

lang 預設為 en。請設定你想要的語言，例如 de 或 es。回應會告訴你實際回傳的字幕軌語言，所以請檢查它，而不是直接假設。一部影片通常只有一條字幕軌，而 API 回傳的是真實字幕，所以它不會替你翻譯。

步驟 5：處理錯誤

從第一天起就為這些情況做好準備：

• 404 no_transcript：影片沒有字幕，或是直播、私人或已移除的影片。沒有什麼可以重試的。略過它，或請使用者換一部影片。
• 402 budget_exceeded：你已達到自己設定的每月點數上限。請見下一節。
• 速率限制：每把金鑰允許每分鐘 60 次請求。批次工作請分散進行，被限制時就放慢速度。
• 我們這邊的失敗：稍後再試一次。這些不收費。

一個在伺服器錯誤時重試、遇到 404 時略過的簡單迴圈，就能涵蓋大多數正式環境的需求。

費用

每份逐字稿費用為 2 點。沒有回傳逐字稿或在 sum.video 端失敗的請求不收費，所以 404 絕不會讓你的餘額減少。你可以用 GET /api/v1/credits 查看餘額。

點數以一次性點數包販售，永遠不會過期：

Pro 訂閱者每月還會額外獲得 100 點贈送點數。對於匯入整個頻道這類大量工作，請閱讀涵蓋自動儲值與預算的情境文章大規模 RAG 應用的 YouTube 逐字稿。也請參考價格。

開始建置前該知道的限制

• 只有有字幕的影片才能使用。這是 404 no_transcript 的主要原因。
• 自動字幕可能有錯誤，尤其是人名、口音與專業術語。
• API 只回傳逐字稿，不會產生摘要。如果你需要摘要、時間戳記以及針對逐字稿的對話，YouTube 摘要工具可以做到，而逐字稿工具則是針對單一影片、免寫程式的版本。
• 官方 YouTube Data API 在這裡無法替代。它下載字幕的方法需要編輯影片的權限，所以是給你自己的影片使用（Google 文件）。

來源

• YouTube Data API: Captions.download
• sum.video 逐字稿 API