結論先說
- 三種傳影片方式按體積和來源選:小於
20 MB的極短片段可內聯字節直傳;本地長影片走 Files API 上載(單文件最大2 GB,必須等狀態變成ACTIVE才能提問);已在 YouTube 公開發布的影片直接傳file_uri連結,免下載免上載。 - 提問和輸出時間戳統一用
MM:SS格式:比如問「02:15到03:40展示了什麼」,或要求模型按MM:SS列出關鍵畫面切換點。 - 只看局部片段就配
video_metadata裁剪:通過start_offset、end_offset和抽幀率fps,只為實際截取的那幾分鐘付 token 費。 - 預設每秒影片約合
258–300 token:摺合一分鐘約1.8 萬 token;長影片把media_resolution調成低檔(low)後可降到每秒約100 token。 - 谷歌帳號準備與多工具訂閱入口:使用 Gemini、Google AI Studio 與 Antigravity 需具備符合地區與年齡要求的個人谷歌帳號,缺號可查看本站 谷歌帳號購買說明(含帶 2FA 的 谷歌電郵成品號),跨平台付費訂閱總覽見 AI 會員充值中心。

圖:本站根據 Gemini API 官方文檔:Video understanding 整理的示意圖
本文根據 Google AI for Developers 官方文檔《Video understanding》《Files API》《Gemini Developer API pricing》整理,資料核對於 2026-11-18。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 Google 官方網站。
適用於誰
- 想用 Gemini API 自動給會議錄像、網課或演示影片生成帶
MM:SS時間戳的章節摘要與字幕的開發者; - 搜「gemini api 影片理解 youtube」,想知道怎麼不下載影片直接把公開 YouTube 網址餵給模型分析的人;
- 傳大影片報
FAILED_PRECONDITION,或想提前算清一小時影片到底消耗多少 token 的人。
一、本地長影片上載(Files API)與必等的 ACTIVE 狀態
先確認已裝好 google-genai SDK 並配置密鑰(準備步驟見 Gemini API Python 調用入門 與 Gemini API Key 獲取教學)。總請求超過 20 MB 時,官方要求先調 client.files.upload。
新手最常踩的坑是剛上載完立刻發生成請求報 400 FAILED_PRECONDITION:影片上載後後台要做抽幀預處理,狀態先處於 PROCESSING,必須輪詢到 ACTIVE 才能餵給模型:
python
import time
from google import genai
client = genai.Client()
video_file = client.files.upload(file="demo_meeting.mp4")
while video_file.state.name == "PROCESSING":
time.sleep(5)
video_file = client.files.get(name=video_file.name)
if video_file.state.name != "ACTIVE":
raise RuntimeError(f"影片處理失敗,狀態:{video_file.state.name}")
response = client.models.generate_content(
model="gemini-2.5-flash",
contents=[
video_file,
"按 MM:SS 時間戳列出核心議題切換點,並總結 01:20 處的結論。",
],
)
print(response.text)
官方提示:請把影片對象放在 contents 列表最前面,文字提問放在後面;Files API 託管文件預設保留 48 小時 後自動清理,不需要繼續複用的敏感錄像也可以主動調 client.files.delete(name=video_file.name) 立即刪除。如果你的影片只有幾秒鐘、連同提示詞整包體積小於 20 MB,也可以跳過上載步驟,直接用 types.Part.from_bytes(data=video_bytes, mime_type="video/mp4") 內聯傳入,省去輪詢等待時間。
二、免下載直傳 YouTube 連結與片段裁剪(video_metadata)
目標影片在 YouTube 上且權限為公開(Public)時,直接用 FileData 傳網址即可。若只看局部幾分鐘,或影片是翻頁很慢的網課,可用 VideoMetadata 指定起止秒數與每秒抽幀數(fps):
python
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-2.5-flash",
contents=types.Content(
parts=[
types.Part(
file_data=types.FileData(file_uri="https://www.youtube.com/watch?v=9hE5-98ZeCg"),
video_metadata=types.VideoMetadata(start_offset="30s", end_offset="150s", fps=0.5),
),
types.Part(text="總結這 2 分鐘片段的操作步驟,標出每步對應的 MM:SS 時間點。"),
]
),
)
print(response.text)
使用 YouTube 直傳需遵守三條官方限制:
- 只支持公開影片:私享(Private)與不公開列出(Unlisted)連結無法讀取;
- 免費層每日時長上限:API 免費層每天累計最多解析 8 小時 YouTube 影片,開通付費層後解除該每日時長上限;
- 抽幀率調節技巧:預設按
1 FPS採樣並同步讀取音軌。快速動作影片可把fps調高到2至5防漏幀;靜態講座調低到0.5可節省大量視覺 token。
三、影片 token 換算規則與報錯排查

圖:本站根據 Gemini API 官方文檔:Video understanding 整理的排錯與省費示意圖
把長影片塞進模型前,建議先按官方口徑估算開銷,避免一次請求把每分鐘 token 限額(TPM)打滿:
| 解像度與抽幀設定 | 每秒約佔 token | 10 分鐘約佔 | 1 小時約佔 | 適用場景 |
|---|---|---|---|---|
| 預設解像度(1 FPS + 音頻) | 約 258–300 | 約 16 萬–18 萬 | 約 95 萬–108 萬 | 需看清畫面小字、代碼框或精細動作的影片 |
低解像度(low)(1 FPS + 音頻) | 約 100 | 約 6 萬 | 約 36 萬 | 長篇訪談、大屏演示、兩三小時錄像塞進百萬窗口 |
超一小時的長影片,建議在 GenerateContentConfig 裏把 media_resolution 設為低解像度(MEDIA_RESOLUTION_LOW)或降低 fps 分段處理;此外新版高級模型還支持可選的智能體影片理解模式(Agentic video understanding),允許模型先檢索時間軸與轉寫文本、再按需拉取關鍵時刻的高清幀,從而大幅壓低超長影片的輸入成本。各模型輸入單價與限流處理詳見 Gemini API 官方價格表 與 Gemini API 429 限流報錯排查。若需準備個人 Google 帳號登入 AI Studio 先免費拖入影片測試,可查看本站 谷歌帳號購買說明 或訪問 充值服務總覽。
常見問題
問:Gemini API 解析影片時只看畫面,還是連說話聲音一起聽?
答:畫面和音軌會同時讀取。即使影片沒有內嵌字幕,模型也能聽懂口播內容並結合畫面標出對應時間戳。
問:為什麼模型給出的時間戳偶爾有一兩秒偏差?
答:因為預設按每秒 1 幀(1 FPS)抽樣。若某個快閃鏡頭只持續半秒,恰好落在兩幀之間就會有秒級誤差;卡點要求高的短影片可在 VideoMetadata 把 fps 設成 2 或更高。
問:能把正在直播的 YouTube Live 連結傳進這個接口嗎?
答:標準 generateContent 接口面向已定長的點播或錄製影片;實時畫面流交互請改用 Gemini Live API(或 AI Studio 的 Stream Realtime 模式)。
問:沒有可用的個人谷歌帳號,或者同時想開其他主流 AI 會員怎麼辦?
答:本站提供即買即發的 谷歌電郵成品號(登入方法見 谷歌帳號購買頁),同時支持支付寶、微信支付與 AlipayHK 自助充值 ChatGPT Plus、Claude Code 等主流服務,實時價格與質保細則以各商品頁說明為準。
相關教學
- Gemini API Python 調用教學:安裝 SDK、流式輸出與多模態輸入
- Gemini API 免費額度是多少:免費層級與 TPM 速率限制查詢
- Gemini API 429 錯誤怎麼解決:RESOURCE_EXHAUSTED 與 400 排查
- Google AI Studio 怎麼用:先在網頁端上載文件調試再導出代碼
參考資料
- Gemini API 官方文檔:Video understanding — https://ai.google.dev/gemini-api/docs/video-understanding
- Gemini API 官方文檔:Files API — https://ai.google.dev/gemini-api/docs/files
- Gemini Developer API pricing — https://ai.google.dev/gemini-api/docs/pricing
0 條評論
還沒有評論,來搶沙發~