內容分析師、UX 使用者研究員與市場調研專家經常需要處理長達數小時的影音記錄——例如使用者易用性測試、焦點團體訪談、學術講座、法人說明會與產業論壇。在傳統流程中，若要從冗長的錄影中擷取結構化事件摘要，通常必須拼湊多套獨立工具：先利用語音辨識（ASR）輸出逐字稿，再以電腦視覺演算法偵測投影片切換，最後人工耗時校對影音時間軸。
Google Gemini 的原生多模態影片理解能力徹底顛覆了這種繁瑣流程。憑藉 100 萬以上 Token 的超長上下文視窗以及原生影音同步處理架構，Gemini 模型（如 Gemini 3.8 Flash、Gemini 3.7 Flash 及 Gemini 2.5 Pro）可直接接收完整的長篇影片檔案。研究人員只需以自然語言提問，就能交叉驗證受訪者言論與螢幕操作畫面，快速定位關鍵時刻，並輸出標註有精準 MM:SS 時間戳記的結構化事件清單。
本文將詳解如何運用 Gemini Files API 上傳並管理長影片、在靜態模式與代理人模式（Agentic Mode）間權衡取捨、利用 JSON Schema 規範輸出格式，並透過上下文快取（Context Caching）大幅降低重複分析的成本與延遲。
一、模式選型：靜態處理 vs 代理人影音理解（Agentic Mode）
Gemini 提供兩種影片處理模式。正確選擇模式是兼顧 Token 開銷、處理效能與分析精確度的核心關鍵。
| 評估維度 | 靜態模式（Static Processing，預設） | 代理人模式（Agentic Video Understanding） |
|---|---|---|
| 運作機制 | 採固定間隔（預設 1 FPS）抽畫格，音訊以 1Kbps 解碼，單次全數載入上下文視窗 | 採用 Think-Act-Observe 迭代循環，模型自主巡檢時間軸，按需載入逐字稿、特定音訊或關鍵影格 |
| Token 開銷 | 低解析度約 100 Token/秒；高解析度約 300 Token/秒 | 長影片最高可節省 88% 輸入 Token；推論消耗思考 Token，按需載入素材計入工具 Token |
| 首字延遲（TTFT） | 短影片（<5 分鐘）反應極快 | 因需在伺服器端進行前置規劃與多輪工具調用，初次回應時間稍長 |
| 適用情境 | 連續逐格視覺稽核、高動態短片、需每秒完整畫面的細緻動作分析 | 15 至 180 分鐘的長錄影、章節標註、關鍵事件搜尋與主題摘要 |
| 支援模型 | 全系列 Gemini 模型 | Gemini 3.8 Flash、Gemini 3.7 Flash、3.6 Flash、3.5 Flash Lite |
什麼時候該採用代理人模式？
凡是長度超過 15 分鐘的長錄影，強烈建議啟用代理人模式（"processing": "agentic"）。傳統將數萬張畫面一次塞入上下文的方式，不僅費用高昂，還容易因資訊雜訊降低聚焦度。代理人模式下，模型會先調閱語音逐字稿定位討論節點，僅在需要核實畫面細節（例如使用者點擊介面按鈕、白板架構圖）時才調取高解析度影格。這項機制能降低高達 66% 的長影音分析費用，並提升約 7% 的綜合回答精確度。
什麼情境必須保留靜態模式？
若研究主題涉及連續的無聲視覺互動——例如觀察受試者的視線軌跡、微表情，或未伴隨口頭說明的細微介面操作，靜態模式能確保時間軸上無任何畫面遺漏。此時，分析人員可微調取樣頻率（例如設定 fps: 0.5 即每兩秒取一格），以在 100 萬 Token 的額度內涵蓋長達 3 小時的觀察素材。
二、透過 Files API 導入長篇影音
當影音檔案大小超過 20MB（或特定端點的 100MB 限制）時，不可使用內嵌 base64 傳輸，必須改用 Files API。Files API 在付費方案支援單一檔案最高 20GB（免費方案支援 2GB），完整支援 MP4、MOV、MPEG、WEBM 與 AVI 等主流格式。
檔案匯入流程分為兩階段：
- 可續傳上傳： 透過 SDK 將原始影音送至 Gemini 儲存端；
- 狀態輪詢： 等待伺服器完成背景轉碼與時間軸切片，檔案狀態由
PROCESSING轉變為ACTIVE。
上傳後的檔案可在專案中保留 48 小時，期間不另收儲存費用，極適合研究團隊在同一工作天內反覆進行多面向質性探索。
三、精準時間戳記提示詞與結構化 JSON 輸出
為了讓多模態模型產出的事件摘要能無縫匯入研究資料庫或視覺化儀表板，必須規範時間格式並強制結構化輸出：
- 統一時間格式標準： Gemini 能原生識別
MM:SS格式（超長影片支援HH:MM:SS）。請在提示詞中明確要求列出事件的起始與結束雙時間戳記。 - 影音跨模態交叉驗證： 提示詞應要求模型比對聲音與視覺的一致性。例如：「請確認受試者在 12:45 表示介面混淆時，畫面上是否確實出現了操作錯誤提示。」
- 強制 JSON Schema 規格： 設定
response_mime_type: "application/json"並綁定 Pydantic 定義，鎖定timestamp_start、timestamp_end、event_type、summary、visual_evidence與verbal_quote欄位，徹底排除多餘的客套文字。 - 提示詞擺放順序： 在 API 請求的輸入陣列中，務必將文字提示詞放置於影片物件之後。
四、Python 完整端到端實作範例
以下範例展示了研究人員如何上傳 60 分鐘的使用者訪談影片，啟用代理人模式與伺服器背景非同步執行（Background Execution），並成功擷取結構化時間戳記摘要：
import time
from google import genai
from google.genai import types
from pydantic import BaseModel, Field
# 1. 初始化用戶端
client = genai.Client()
# 2. 透過 Files API 上傳長篇影片
print("正在上傳訪談錄影檔案...")
video_file = client.files.upload(
file="user_research_session_04.mp4",
config={"mime_type": "video/mp4"}
)
# 3. 輪詢確認伺服器轉碼索引完成
while video_file.state.name == "PROCESSING":
print("伺服器正在進行轉碼與時間軸索引，5 秒後重新檢查...")
time.sleep(5)
video_file = client.files.get(name=video_file.name)
if video_file.state.name == "FAILED":
raise RuntimeError("影片伺服器轉碼失敗，請確認檔案格式是否正確。")
print(f"影片已啟用，資源 URI: {video_file.uri}")
# 4. 定義事件摘要的結構化資料模型
class VideoEvent(BaseModel):
timestamp_start: str = Field(description="事件開始時間（MM:SS 格式）")
timestamp_end: str = Field(description="事件結束時間（MM:SS 格式）")
event_type: str = Field(description="事件類別：痛點、功能建議、操作障礙或討論結論")
summary: str = Field(description="事件簡短說明")
visual_evidence: str = Field(description="螢幕或肢體畫面觀察到的佐證")
verbal_quote: str = Field(description="受訪者關鍵原話口頭陳述")
class ResearchSummary(BaseModel):
video_overview: str = Field(description="整場訪談的執行摘要")
events: list[VideoEvent] = Field(description="依時間序排列的結構化事件清單")
# 5. 發起代理人模式分析並啟用背景非同步執行
# background=True 能避免長時間深度推理發生連線或憑證逾時
prompt_text = """
請深入分析這段使用者研究訪談錄影。
列出受試者遭遇的所有易用性障礙、新功能期望與重大決策時刻。
交叉比對口頭反饋與螢幕畫面操作，依時間順序輸出標註有精確 MM:SS 時間戳記的事件。
"""
print("正在提交代理人影片分析任務...")
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{
"type": "video",
"uri": video_file.uri,
"mime_type": video_file.mime_type,
"processing": "agentic" # 啟用代理人動態巡檢
},
{
"type": "text",
"text": prompt_text
}
],
response_mime_type="application/json",
response_schema=ResearchSummary,
background=True # 伺服器端非同步執行
)
# 6. 輪詢等待背景任務完成
while interaction.status == "in_progress":
print("模型正在多步巡檢影片時間軸並整合證據...")
time.sleep(5)
interaction = client.interactions.get(interaction.id)
print("\n--- 擷取結果清單 ---")
print(interaction.output_text)
五、善用上下文快取（Context Caching）支援高頻多輪分析
在質性研究情境中，分析師很少只向同一支影片發問一次。通常需要先提取會議章程，再接續探討品牌競品評價、使用者情緒起伏，或針對特定流程深度剖析。
若每次提問都重新傳遞 90 分鐘的完整影片，運算費用與等待時間將大幅飆升。Gemini 的上下文快取功能可完美解決此問題：
- 大幅降低成本： 快取命中的輸入 Token 費用通常僅為標準輸入價格的 10% 到 20%。
- 加速推論速度： 影音內容已預先完成記憶體向量化，首字產出時間明顯縮短。
- 實務作法： 透過
generateContentAPI，為目標影片建立指定有效期限（TTL，例如 2 小時）的顯式快取物件。後續所有提問僅需指向cachedContents/<cache-id>，即可讓整個團隊經濟高效地進行數十輪深入探索。
六、實務注意事項與除錯建議
- 防範連線中斷逾時： 針對 15 分鐘以上的影音，深度推理可能需時數分鐘，傳統同步 HTTP 連線容易遭遇閘道逾時或存取權杖過期（如回傳
401 Unauthorized）。強烈建議在 Interactions API 啟用background=True，或在 generateContent 中改採串流傳輸（stream=True）。 - 驗證代理人巡檢痕跡： 檢查代理人模式回傳物件中的
interaction.steps。若包含processing_call與processing_result步驟，即代表模型確實動態載入了時間片段，而非憑空臆測。 - 靈活設定畫面解析度： 若需辨識畫面上的小字元、試算表數字或程式碼細節，請指名
media_resolution: "high"；若僅需掌握討論脈絡與一般簡報切換，預設低解析度（每格 66 Token）即可提供絕佳性價比。 - 預留時間範圍容錯： 語音發話與畫面顯示常有微幅時差。提示詞索取時間範圍（
timestamp_start至timestamp_end），在後續回溯剪輯時的命中率顯著高於單一時間點。