影片理解 API

API易通過 Gemini 系列多模態模型提供影片理解能力：用一段提示詞，讓模型”看懂”影片裡的場景、動作、字幕與音訊，並按時間戳定位關鍵畫面。本頁說明支援的模型、可用的影片輸入方式，以及最容易踩坑的限制。

先看這一條：影片只能通過 Base64 內聯（整個請求 ≤ 20MB） 或 YouTube 連結（Gemini 原生格式）傳入。直接傳公開影片直鏈（如 https://example.com/demo.mp4）會報 Request contains an invalid argument —— 這是谷歌不接收直鏈，並非 API易攔截。詳見下方「影片輸入方式」。

視覺化介面測試

在 iCover 視覺化測試工具裡直接上傳影片、除錯理解介面。

支援的模型

模型	模型 ID	特點	推薦場景
Gemini 3.5 Flash 🔥	`gemini-3.5-flash`	速度快、價效比之王，多模態能力強	日常影片分析首選
Gemini 3.1 Pro Preview	`gemini-3.1-pro-preview`	谷歌最強推理 + 多模態理解	複雜、長影片深度分析
Gemini 3.1 Flash Lite	`gemini-3.1-flash-lite`	超低價、超低延遲	大批次、高併發場景

經典穩定版 gemini-2.5-pro（2M 上下文）與 gemini-2.5-flash 仍可用。完整價格見模型列表與價格。

影片輸入方式

這是最容易踩坑的地方，請先對照下表確認你的輸入方式是否被支援：

輸入方式	是否支援	說明
Base64 內聯	✅	本地影片讀取後 base64 編碼傳入，整個請求體需 ≤ 20MB。OpenAI 相容格式與原生格式都支援
YouTube 連結	✅	僅 Gemini 原生格式，通過 `file_uri` 傳入 YouTube URL
公開影片直鏈（如 `.mp4` 網址）	❌	谷歌不接收，會返回 `Request contains an invalid argument`，並非 API易攔截
Files API（`files.upload`）	❌	第三方不支援，僅谷歌官方支援

20MB 限制：Base64 方式下，整個請求體（含編碼後的影片）必須在 20MB 以內。超過 20MB 的影片目前只能：① 用 YouTube 連結；② 先本地壓縮 / 擷取片段到 20MB 內再 base64。

快速開始：Base64 內聯（OpenAI 相容格式）

最常用的方式：讀取本地影片 → base64 編碼 → 用 image_url 欄位傳入。

from openai import OpenAI
import base64

client = OpenAI(
    api_key="YOUR_API_KEY",            # 替換為您的 API易 金鑰
    base_url="https://api.apiyi.com/v1"
)

{/* 讀取本地影片並轉 base64（整個請求 ≤ 20MB）*/}
with open("demo.mp4", "rb") as f:
    video_b64 = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "請詳細描述這個影片的內容"},
            {
                "type": "image_url",
                "image_url": {"url": f"data:video/mp4;base64,{video_b64}"},
                "mime_type": "video/mp4",
            },
        ],
    }],
)

print(response.choices[0].message.content)

curl 等價寫法（把 <BASE64_VIDEO> 替換為影片的 base64 字串；體積較大時建議直接用 SDK 自動編碼）：

curl https://api.apiyi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "請總結這個影片"},
        {"type": "image_url",
         "image_url": {"url": "data:video/mp4;base64,<BASE64_VIDEO>"},
         "mime_type": "video/mp4"}
      ]
    }]
  }'

YouTube 連結（Gemini 原生格式）

YouTube 連結無需下載、不受 20MB 限制，但只能通過 Gemini 原生格式傳入（google-genai SDK，端點 https://api.apiyi.com）。

from google import genai
from google.genai import types

client = genai.Client(
    api_key="YOUR_API_KEY",
    http_options={"base_url": "https://api.apiyi.com"}
)

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents=types.Content(parts=[
        types.Part(file_data=types.FileData(
            file_uri="https://www.youtube.com/watch?v=VIDEO_ID"
        )),
        types.Part(text="請總結這個影片的主要內容和關鍵資訊"),
    ]),
)

print(response.text)

原生格式的更多用法（流式、推理預算、Function Calling 等）見 Gemini 原生格式呼叫。

進階技巧

時間戳定位

模型預設按 1 幀/秒取樣並理解音訊，你可以在提示詞裡用 MM:SS 直接定位片段——這是純提示詞技巧，任意輸入方式都可用：

請描述 00:30 到 01:15 之間發生了什麼，並指出 02:40 出現的文字內容。

常見任務的提問思路

同一段影片，換提示詞就能完成不同分析，無需改程式碼：

內容摘要：用 3-5 句話概括影片主題、關鍵畫面與結論
教學分析：提取知識點、章節劃分與重點時間戳
監控分析：識別異常行為、出現的人/物及發生時間
營銷評估：分析產品賣點呈現、節奏與目標受眾契合度
動作分析：拆解動作步驟、姿態要點與可改進之處

技術說明

取樣幀率：預設按 1 幀/秒（FPS） 取樣，同時理解音訊軌。
Token 消耗：預設解析度約 300 tokens/秒，低解析度約 100 tokens/秒——影片越長，token 越多，請據此估算成本。
支援格式：mp4、mpeg、mov（quicktime）、avi、webm、wmv、3gpp 等常見格式。

常見問題

傳公開影片連結報錯 Request contains an invalid argument / 拉取失敗

谷歌的影片理解不接收任意公開直鏈（如 https://example.com/video.mp4），會返回 Request contains an invalid argument。這不是 API易或 Nginx 攔截。請改用：① Base64 內聯（≤20MB）；② YouTube 連結（原生格式）。

為什麼限制 20MB？之前明明能用

Base64 內聯方式下，整個請求體一直限制在 20MB 以內（與谷歌官方一致）。如果你”之前能用”的是公開直鏈，那其實從來不是受支援的方式，只是恰好某些情況下沒報錯；現在按規範會明確拒絕。

能用 files.upload 上傳大影片嗎？

不能。Gemini 官方的 Files API（client.files.upload()）第三方不支援，僅谷歌官方端點可用。大影片請走 YouTube 連結，或壓縮到 20MB 內用 Base64。

超過 20MB 的影片怎麼辦？

兩條路：① 上傳到 YouTube 後用連結傳入（原生格式，不受 20MB 限制）；② 用 ffmpeg 等工具本地壓縮或擷取關鍵片段到 20MB 內再 base64。

模型列表與價格

檢視全部 Gemini 模型與最新定價

Gemini 原生格式

YouTube 連結、流式、推理預算等原生用法

影像理解 API

圖片內容識別與多模態分析

API 文件

完整 API 規範與端點說明

產品基礎

基礎 API

圖片 API（官轉）

影片 API（官轉）

多模態理解 API

文本 API

視覺化介面測試

支援的模型

影片輸入方式

快速開始：Base64 內聯（OpenAI 相容格式）

YouTube 連結（Gemini 原生格式）

進階技巧

時間戳定位

常見任務的提問思路

技術說明

常見問題

相關資源

模型列表與價格

Gemini 原生格式

影像理解 API

API 文件

視覺化介面測試

​支援的模型

​影片輸入方式

​快速開始：Base64 內聯（OpenAI 相容格式）

​YouTube 連結（Gemini 原生格式）

​進階技巧

​時間戳定位

​常見任務的提問思路

​技術說明

​常見問題

​相關資源

模型列表與價格

Gemini 原生格式

影像理解 API

API 文件

支援的模型

影片輸入方式

快速開始：Base64 內聯（OpenAI 相容格式）

YouTube 連結（Gemini 原生格式）

進階技巧

時間戳定位

常見任務的提問思路

技術說明

常見問題

相關資源