Gemini API 如何補足 YouTube 無字幕影片？Scribis 的 timedtext、翻譯與多語言 TTS 工作流程

YouTube iframe、Gemini 影片理解、字幕翻譯與本地多語言 TTS 的概念圖

對想觀看外語教學、訪談或知識型影片的使用者而言，字幕是理解內容的第一道門檻；當影片沒有字幕，或字幕語言不符合需求時，跨語言觀看就會變得困難。Scribis 的 YouTube 字幕功能，並不是把影片下載下來再重新處理，而是以 iframe 播放 YouTube，讓即時轉錄跟隨播放中的音訊進行；同時，只有在 YouTube 被動提供 timedtext 時，Scribis 才會擷取可用的字幕文字。

當影片完全沒有 timedtext 字幕時，Gemini API 可以作為另一條內容理解路徑：將公開 YouTube 網址傳給 Gemini，請它根據影片中的語音與畫面產生字幕草稿，再交給 Scribis 翻譯，最後透過本地 Text to Speech（TTS）產生不同語言的語音輸出。

**簡單說：**Scribis 不負責下載 YouTube 影音，也不在這項流程中匯出音訊、影片或字幕檔案。它負責在播放情境中取得可用字幕、即時轉錄、翻譯字幕，並以本地 TTS 讓使用者直接享受多語言輸出。

先釐清：這不是 YouTube 下載器

理解這套流程的關鍵，是把「播放」、「字幕擷取」與「影片下載」分開。Scribis 的 YouTube 功能透過 iframe 嵌入播放器；播放時，系統可以同步取得正在播放的音訊，交給即時轉錄流程處理。這個流程不等於把完整音訊檔案下載到本機，也不等於把 YouTube 影片保存成檔案。

同樣地，timedtext 是字幕文字與時間資訊的來源，不是音訊軌。Scribis 只在 YouTube 被動提供 timedtext 時擷取它；如果影片沒有可用字幕，就不會因為「想要字幕」而主動向 YouTube 發出字幕請求。即使 Scribis 提供 yt-dlp 支援，本文所說的 YouTube 字幕流程也不以 yt-dlp 下載影片、音訊或字幕為目的，而是讓即時轉錄跟隨 iframe 播放中的音訊工作。

元件	在這套流程中的角色	不代表什麼
YouTube iframe	在 Scribis 內嵌並播放影片	不代表下載影片檔或保存完整影音
播放中的音訊	提供即時轉錄所需的聆聽來源	不代表匯出音訊檔
`timedtext`	YouTube 有提供時，作為字幕與時間資訊來源	不代表讀取或下載影片音軌
Gemini API	當影片沒有字幕時，理解公開 YouTube 影片並產生字幕草稿	不等於取得 YouTube 原生字幕，也不授予內容重製權
本地 TTS	將翻譯後的字幕轉成多語言語音，讓使用者在 Scribis 中直接聆聽	不代表輸出獨立配音檔或重新發布影片

Scribis 的實際工作流程

Scribis 以 iframe 播放 YouTube、被動檢查 timedtext，無字幕時以 Gemini 產生字幕，再翻譯並以本地 TTS 輸出多語言語音

圖：Scribis YouTube 字幕與多語言語音的實際流程；流程不包含下載或檔案匯出。

整個流程可以分成兩條字幕來源路徑。第一條是正常路徑：使用者在 Scribis 內以 iframe 播放 YouTube，播放音訊同步進入即時轉錄；如果 YouTube 同時提供 timedtext，Scribis 就被動擷取這些字幕資料，作為字幕顯示與後續翻譯的來源。第二條是備援路徑：如果沒有可用 timedtext，Scribis 才需要透過 Gemini API 對公開 YouTube URL 進行影片理解，取得字幕內容草稿，再讓使用者進行翻譯與語音輸出。

這個設計可以避免把所有影片都送到 Gemini，也避免把字幕功能誤解成下載功能。對本來就有字幕的影片，優先使用 YouTube 已提供的 timedtext；只有在缺少字幕時，才啟用需要額外推論與校對的 Gemini 路徑。

Gemini API 如何處理 YouTube URL？

Google 官方文件目前支援把 YouTube 網址直接放在 Gemini API 的影片輸入中。請求使用 type: "video" 表示影片輸入，再以 uri 放入完整 YouTube URL，並搭配文字提示要求摘要、逐句內容、時間戳記或字幕草稿。

官方文件也將這項 YouTube URL 功能標示為預先發布版，並提醒價格與速率限制可能變更。因此，若要在 Scribis 的正式功能中長期使用，應保留模型、配額與 API 行為更新的彈性。

Python 最小範例

先安裝 Google GenAI Python SDK：

pip install google-genai

再把 API 金鑰放在環境變數中。不要把金鑰寫死在前端程式碼、公開儲存庫或可被使用者讀取的設定檔中。

export GEMINI_API_KEY="你的_Gemini_API_金鑰"

以下範例示範「影片沒有可用字幕時，請 Gemini 產生字幕草稿」的做法：

from google import genai
import os

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

youtube_url = "https://www.youtube.com/watch?v=你的影片ID"

prompt = """
請分析這部公開 YouTube 影片，產生可供字幕編輯的繁體中文初稿。
請僅根據影片中能確認的語音與畫面內容回答，並依照以下格式輸出：

一、影片語言與內容簡介
二、逐段字幕內容：每段包含開始時間、結束時間與字幕文字
三、重要事件與關鍵畫面，時間格式使用 MM:SS
四、人名、品牌名、產品名、技術名詞與原文拼寫
五、無法確認的地方，請標示「需要人工校對」

字幕要求：
- 每段最多兩行。
- 使用自然、適合閱讀的繁體中文。
- 不要自行補完聽不清楚的句子。
- 如果無法可靠判斷時間，請標示為估計時間。
"""

interaction = client.interactions.create(
    model="gemini-3.6-flash",
    input=[
        {"type": "video", "uri": youtube_url},
        {"type": "text", "text": prompt},
    ],
    store=False,
)

print(interaction.output_text)

這段程式的重點不在於讓 Gemini 取代字幕編輯器，而是讓它在「YouTube 沒有可用字幕」時，產生一份可以繼續校對的字幕內容。type: "video" 與 uri 負責指定影片來源；文字提示則規定字幕格式、時間戳記、語言與不確定內容的標記方式。

store=False 是可選的資料管理設定。Interactions API 預設會儲存互動；如果不需要後續使用 previous_interaction_id 延續狀態，可以選擇不儲存。但設定為 False 後，就不能依賴伺服器端的後續互動狀態。實際部署時，應根據內容敏感度、除錯需求與資料保留政策決定設定。

為什麼要指定時間戳記與字幕格式？

如果只輸入「請總結這部影片」，Gemini 可能回傳一篇適合閱讀的摘要，卻不一定適合拿來做字幕。要讓結果能接上 Scribis，提示詞應要求短句、逐段內容、時間戳記、名詞表與不確定標記。

Google 官方文件支援用 MM:SS 格式參照影片中的特定時間點。例如，當你要檢查教學影片中的操作示範，可以這樣問：

請分析 02:15、08:40 與 14:05 三個時間點。
對每個時間點輸出：正在說明的主題、畫面中的關鍵動作、最適合放入字幕的一句話。
如果無法確認說話者或畫面文字，請明確標示「需要人工校對」。

對字幕草稿而言，時間戳記應被視為「定位線索」，而不是未經檢查的最終剪輯標記。Scribis 的價值就在於，使用者可以對照 iframe 播放內容與即時轉錄結果，修正段落、名詞、數字與閱讀節奏。

Gemini 無字幕備援，與 timedtext 有什麼不同？

這兩者是不同來源，不應混為一談。timedtext 是 YouTube 在影片上提供的字幕文字與時間資訊；它存在時，Scribis 可以被動擷取，無須自行理解整段影片。Gemini API 則是影片理解模型：當影片沒有可用字幕時，透過公開 YouTube URL 讀取影片內容，根據語音與影像產生新的文字結果。

因此，Gemini 產生的字幕不是「取回 YouTube 原字幕」，而是「根據影片內容建立字幕草稿」。這也說明了為什麼它必須經過人工檢查：模型可能聽錯專有名詞、漏掉快速發言、誤判說話者，或把畫面上的文字理解錯誤。

Google 官方說明指出，Gemini 的視覺描述預設以每秒 1 個影格取樣；快速動作或快速場景切換可能遺漏細節。所以，當影片是遊戲操作、軟體教學、實驗示範或投影片錄製時，應特別檢查關鍵片段，而不能把 Gemini 初稿直接視為完整逐字稿。

從字幕到多語言 TTS：Scribis 的使用情境

當字幕來源已經確定後，Scribis 的後續工作就很清楚。若影片有 timedtext，先使用它作為字幕底稿；若沒有，先使用 Gemini 生成字幕內容，再把草稿放入相同的字幕校對流程。兩種來源最後都會進入同一條多語言輸出路徑。

第一步是校對原文字幕。請確認人名、品牌、數字、單位、技術名詞與句子分段，並將 Gemini 標記的「需要人工校對」片段逐一回看。字幕的目標不是把所有模型輸出原封不動顯示出來，而是建立觀眾能在播放節奏中讀懂的文字。

第二步是翻譯。翻譯時應保留時間軸對應，並建立固定術語翻譯，例如產品名稱、技術詞彙與人名不要在不同字幕段落中任意變化。對英文、日文、韓文或其他語言，還要留意句長與語序改變，以免翻譯後字幕來不及閱讀。

第三步是使用本地 TTS。Scribis 可以把翻譯後的字幕文字交給本地 TTS，產生不同語言的語音輸出，讓使用者在播放情境中直接享受多語言內容。這裡的重點是「播放與聆聽體驗」，不是把音訊另存成檔案，也不是重新封裝或匯出 YouTube 影片。

階段	內容來源	使用者得到的結果
有字幕	YouTube 被動提供的 `timedtext`	可在 Scribis 中顯示、校對與翻譯的字幕內容
無字幕	Gemini 以 YouTube URL 進行影片理解	可供校對的字幕草稿、摘要與時間定位
翻譯	校對後的原文字幕	對應同一播放時間軸的目標語言字幕
本地 TTS	翻譯後字幕文字	播放情境中的多語言語音輸出

YouTube URL 的限制與實務取捨

Google 官方文件列出的限制包括：YouTube URL 功能目前為預先發布版；免費方案每天最多可上傳 8 小時的 YouTube 影片；付費方案沒有影片長度限制；Gemini 2.5 之前的模型每次要求只能使用一部影片，Gemini 2.5 以上版本每個要求最多可使用十部影片；而且只能使用公開影片，私人或不公開影片無法透過這種方式處理。

這些限制會影響 Scribis 的產品策略。對有 timedtext 的影片，不需要動用 Gemini；只有「沒有字幕」的影片才進入 Gemini 備援，因此可以把 API 用量集中在真正需要內容理解的情境。對長影片或需要反覆提問的內容，也應持續觀察官方文件與模型政策，而不是假設預先發布功能的限制永遠不變。

常見問題

問題	正確理解	建議做法
Scribis 會下載 YouTube 影片嗎？	不會。本文流程透過 iframe 播放，不以下載影片檔為前提。	將功能描述為播放、即時轉錄與字幕處理，不要稱為下載。
Scribis 會下載或匯出 YouTube 音訊嗎？	不會。即時轉錄跟隨播放中的音訊工作，不等於取得獨立音訊檔。	說明為「播放時的即時轉錄」。
Scribis 會主動 request timedtext 嗎？	不會。只有在 YouTube 被動提供可用 `timedtext` 時才擷取。	沒有字幕時，改走 Gemini 影片理解備援。
Gemini 取得的是 YouTube 原字幕嗎？	不一定。無字幕情境下，是 Gemini 根據影片內容生成字幕草稿。	在 UI 與文章中使用「產生字幕內容／字幕草稿」等準確說法。
Gemini 產生的字幕能直接發布嗎？	不應直接視為最終版本。	回看原片，檢查時間、名詞、數字、說話者與翻譯。
本地 TTS 是不是輸出配音檔？	本文描述的是播放情境中的多語言語音輸出，不涉及音訊檔匯出。	強調使用者可直接聆聽多語言內容。
API 金鑰可以放在前端嗎？	不建議。Google 官方要求妥善保管金鑰，不要在正式用戶端硬式編碼。	使用環境變數與受保護的後端或本機安全執行環境。

結語：以字幕可用性決定是否啟用 Gemini

Scribis 的 YouTube 字幕流程，核心並不是把影片搬到另一個地方處理，而是在使用者觀看影片的當下，盡可能取得可用的文字內容。播放器透過 iframe 讓音訊跟隨播放，系統被動等待 YouTube 提供 timedtext；有字幕就使用現成字幕，沒有字幕才交由 Gemini API 根據公開 YouTube 影片產生字幕草稿。

這樣的分層設計有三個優點：它不把字幕功能誤解成下載功能，不會在沒有 timedtext 時主動向 YouTube 請求字幕，也能在真正缺少字幕的影片上，以 Gemini 補足內容理解。字幕經過校對與翻譯後，再由本地 TTS 轉成多語言語音，讓使用者能直接享受更完整的跨語言觀看體驗。

**最適合對外溝通的一句話：**Scribis 讓 YouTube 影片在播放時取得可用字幕；有 timedtext 就被動擷取，沒有字幕就以 Gemini 產生字幕內容，翻譯後再用本地 TTS 提供多語言語音輸出。