您可以在 Gemini 要求中加入影片，執行需要理解影片內容的工作。本頁面說明如何使用 Google Cloud 控制台和 Agent Platform API，在 Gemini Enterprise Agent Platform 中，將影片新增至 Gemini 要求。
支援的模型
下表列出支援影片理解功能的模型：
| 模型 | 媒體詳細資料 | MIME 類型 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
如需 Gemini 模型支援的語言清單，請參閱 Google 模型的資訊。如要進一步瞭解如何設計多模態提示詞，請參閱「設計多模態提示詞」。如要直接從行動和網頁應用程式使用 Gemini，請參閱 Firebase AI Logic 用戶端 SDK，適用於 Swift、Android、網頁、Flutter 和 Unity 應用程式。
新增影片至要求
您可以在傳送給 Gemini 的要求中加入一或多部影片，影片可以包含音訊。
單一影片
下列各分頁中的程式碼範例，示範了辨識影片內容的不同方式。這個範例適用於所有多模態版 Gemini 模型。
控制台
如要使用 Google Cloud 控制台傳送多模態提示，請按照下列步驟操作：前往 Google Cloud 控制台「Agent Platform」部分的「Agent Studio」頁面。
按一下「建立提示」。
選用步驟：設定模型和參數：
- 模型：選取模型。
選用步驟：如要設定進階參數，請按一下「Advanced」(進階)，然後按照下列指示操作：
按一下即可展開進階設定
Top-K：使用滑桿或文字方塊輸入 Top-K 值。
「Top-K」會影響模型選取輸出符記的方式。如果 Top-K 設為1，代表下一個所選詞元是模型詞彙表的所有詞元中可能性最高者 (也稱為「貪婪解碼」)。如果 Top-K 設為3，則代表模型會依據溫度參數，從可能性最高的 3 個詞元中選取下一個詞元。在每個符記選取步驟中，模型會對機率最高的「Top-K」符記取樣，接著進一步根據「Top-P」篩選詞元，最後依 temperature 選出最終詞元。
如要取得較不隨機的回覆，請指定較低的值；如要取得較隨機的回覆，請調高此值。
- Top-P：使用滑桿或文字方塊輸入 Top-P 值。
模型會按照可能性最高到最低的順序選取詞元，直到所選詞元的可能性總和等於 Top-P 值。如要讓結果的變化性降到最低，請將 Top-P 設為
0。 - 回覆數量上限：使用滑桿或文字方塊，輸入要生成的回覆數量。
- 串流回覆：啟用後，系統會顯示正在生成的回覆。
- 安全篩選器門檻：選取看見可能有害回應的機率門檻。
- 啟用建立基準：多模態提示不支援建立基準。
- Region (區域)：選取要使用的區域。
- 溫度：使用滑桿或文字方塊輸入溫度值。
The temperature is used for sampling during response generation, which occurs whentopPandtopKare applied. Temperature controls the degree of randomness in token selection. Lower temperatures are good for prompts that require a less open-ended or creative response, while higher temperatures can lead to more diverse or creative results. A temperature of0means that the highest probability tokens are always selected. In this case, responses for a given prompt are mostly deterministic, but a small amount of variation is still possible.If the model returns a response that's too generic, too short, or the model gives a fallback response, try increasing the temperature. If the model enters infinite generation, increasing the temperature to at least
0.1may lead to improved results.1.0is the recommended starting value for temperature. </li> <li>**Output token limit**: Use the slider or textbox to enter a value for the max output limit. Maximum number of tokens that can be generated in the response. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words.Specify a lower value for shorter responses and a higher value for potentially longer responses.
</li> <li>**Add stop sequence**: Optional. Enter a stop sequence, which is a series of characters that includes spaces. If the model encounters a stop sequence, the response generation stops. The stop sequence isn't included in the response, and you can add up to five stop sequences.</li> </ul>
按一下「插入媒體」，然後選取檔案來源。
上傳
選取要上傳的檔案，然後按一下「開啟」。
使用網址上傳
輸入要使用的檔案網址，然後按一下「插入」。
YouTube
輸入要使用的 YouTube 影片網址，然後按一下「Insert」(插入)。
您可以使用任何公開影片，或登入 Google Cloud 控制台的帳戶所擁有的影片。
Cloud Storage
依序選取 bucket 和要匯入的檔案，然後按一下「Select」(選取)。
Google 雲端硬碟
- 首次選取這個選項時，請選擇帳戶並授予 Agent Studio 存取權。您可以上傳多個檔案，總大小上限為 10 MB。單一檔案不得超過 7 MB。
- 按一下要新增的檔案。
按一下「選取」。
檔案縮圖會顯示在「提示詞」窗格中。系統也會顯示權杖總數。如果提示資料超出詞元限制，系統會截斷詞元，且不會納入處理資料。
在「提示」窗格中輸入文字提示詞。
選用：如要查看「Token ID to text」(詞元 ID 轉文字) 和「Token IDs」(詞元 ID)，請按一下「Prompt」(提示) 窗格中的「tokens count」(詞元數量)。
按一下「提交」。
選用：如要將提示詞儲存到「我的提示詞」，請依序點按 和「儲存」。
選用：如要取得提示的 Python 程式碼或 curl 指令，請依序點選 「Build with code」>「Get code」。
Python
安裝
pip install --upgrade google-genai
詳情請參閱 SDK 參考文件。
設定環境變數，以便透過 Vertex AI 使用 Google Gen AI SDK：
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Go
詳情請參閱 SDK 參考文件。
設定環境變數，以便透過 Vertex AI 使用 Google Gen AI SDK：
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Java
詳情請參閱 SDK 參考文件。
設定環境變數，以便透過 Vertex AI 使用 Google Gen AI SDK：
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Node.js
安裝
npm install @google/genai
詳情請參閱 SDK 參考文件。
設定環境變數，以便透過 Vertex AI 使用 Google Gen AI SDK：
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
REST
設定環境後，您可以使用 REST 測試文字提示詞。下列範例會將要求傳送至發布者模型端點。
使用任何要求資料之前，請先修改下列項目的值：
PROJECT_ID：您的專案 ID。。FILE_URI：要加入提示的檔案 URI 或網址。可接受的值包括：- Cloud Storage bucket URI：物件必須可公開讀取，或位於傳送要求的 Google Cloud 專案中。
- HTTP 網址：檔案網址必須可公開讀取。每項要求可指定一個影片檔案、一個音訊檔案和最多 10 個圖片檔。音訊檔案、影片檔案和文件不得超過 15 MB。
- YouTube 影片網址：YouTube 影片必須由您用來登入 Google Cloud 控制台的帳戶擁有，或設為公開。每項要求僅支援一個 YouTube 影片網址。
指定
fileURI時，也必須指定檔案的媒體類型 (mimeType)。如果啟用 VPC Service Controls，則不支援為fileURI指定媒體檔案網址。如果 Cloud Storage 中沒有影片檔案，可以使用下列公開檔案：
gs://cloud-samples-data/video/animals.mp4，MIME 類型為video/mp4。如要觀看這部影片，請開啟 MP4 範例檔案。MIME_TYPE：data或fileUri欄位中指定檔案的媒體類型。可接受的值包括：按一下即可展開 MIME 類型
application/pdfaudio/mpegaudio/mp3audio/wavimage/pngimage/jpegimage/webptext/plainvideo/movvideo/mpegvideo/mp4video/mpgvideo/avivideo/wmvvideo/mpegpsvideo/flv
TEXT：提示中要包含的文字指示。例如：What is in the video?
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中。
在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：
cat > request.json << 'EOF'
{
"contents": {
"role": "USER",
"parts": [
{
"fileData": {
"fileUri": "FILE_URI",
"mimeType": "MIME_TYPE"
}
},
{
"text": "TEXT"
}
]
}
}
EOF接著執行下列指令，傳送 REST 要求：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent"
PowerShell
將要求主體儲存在名為 request.json 的檔案中。
在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：
@'
{
"contents": {
"role": "USER",
"parts": [
{
"fileData": {
"fileUri": "FILE_URI",
"mimeType": "MIME_TYPE"
}
},
{
"text": "TEXT"
}
]
}
}
'@ | Out-File -FilePath request.json -Encoding utf8接著執行下列指令，傳送 REST 要求：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent" | Select-Object -Expand Content
您應該會收到如下的 JSON 回覆。
請注意這個範例網址中的下列部分：- 使用
generateContent方法，要求在回覆完全生成後傳回。如要減少人類觀眾對延遲時間的感知，請使用streamGenerateContent方法，在生成回覆時串流回覆。 - 多模態模型 ID 位於網址結尾，在方法之前 (例如
gemini-3.5-flash)。這個範例可能也支援其他模型。 - 使用區域 API 端點 (例如
us-central1) 時，系統會根據端點網址中的區域，決定處理要求的位置。系統會忽略資源路徑中任何衝突的位置。
有聲影片
以下說明如何總結含有音訊的影片檔案，並傳回含有時間戳記的章節。這個範例適用於所有支援影片和音訊的多模態版 Gemini 模型。
Python
安裝
pip install --upgrade google-genai
詳情請參閱 SDK 參考文件。
設定環境變數，以便透過 Vertex AI 使用 Google Gen AI SDK：
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
REST
設定環境後，您可以使用 REST 測試文字提示詞。下列範例會將要求傳送至發布者模型端點。
使用任何要求資料之前，請先修改下列項目的值：
PROJECT_ID：FILE_URI：要加入提示的檔案 URI 或網址。可接受的值包括：- Cloud Storage bucket URI：物件必須可公開讀取，或位於傳送要求的 Google Cloud 專案中。
- HTTP 網址：檔案網址必須可公開讀取。每項要求可指定一個影片檔案、一個音訊檔案和最多 10 個圖片檔。音訊檔案、影片檔案和文件不得超過 15 MB。
- YouTube 影片網址：YouTube 影片必須由您用來登入 Google Cloud 控制台的帳戶擁有，或設為公開。每項要求僅支援一個 YouTube 影片網址。
指定
fileURI時，也必須指定檔案的媒體類型 (mimeType)。如果啟用 VPC Service Controls，則不支援為fileURI指定媒體檔案網址。如果 Cloud Storage 中沒有影片檔案，可以使用下列公開檔案：
gs://cloud-samples-data/generative-ai/video/pixel8.mp4，MIME 類型為video/mp4。如要觀看這部影片，請開啟 MP4 範例檔案。MIME_TYPE：data或fileUri欄位中指定檔案的媒體類型。可接受的值包括：按一下即可展開 MIME 類型
application/pdfaudio/mpegaudio/mp3audio/wavimage/pngimage/jpegimage/webptext/plainvideo/movvideo/mpegvideo/mp4video/mpgvideo/avivideo/wmvvideo/mpegpsvideo/flv
TEXT
Provide a description of the video. The description should also contain anything important which people say in the video.
如要傳送要求，請選擇以下其中一個選項：
curl
將要求主體儲存在名為 request.json 的檔案中。
在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：
cat > request.json << 'EOF'
{
"contents": {
"role": "USER",
"parts": [
{
"fileData": {
"fileUri": "FILE_URI",
"mimeType": "MIME_TYPE"
}
},
{
"text": "TEXT"
}
]
}
}
EOF接著執行下列指令，傳送 REST 要求：
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent"
PowerShell
將要求主體儲存在名為 request.json 的檔案中。
在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：
@'
{
"contents": {
"role": "USER",
"parts": [
{
"fileData": {
"fileUri": "FILE_URI",
"mimeType": "MIME_TYPE"
}
},
{
"text": "TEXT"
}
]
}
}
'@ | Out-File -FilePath request.json -Encoding utf8接著執行下列指令，傳送 REST 要求：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent" | Select-Object -Expand Content
您應該會收到如下的 JSON 回覆。
請注意這個範例網址中的下列部分：- 使用
generateContent方法，要求在回覆完全生成後傳回。如要減少人類觀眾對延遲時間的感知，請使用streamGenerateContent方法，在生成回覆時串流回覆。 - 多模態模型 ID 位於網址結尾，在方法之前 (例如
gemini-3.5-flash)。這個範例可能也支援其他模型。 - 使用區域 API 端點 (例如
us-central1) 時，系統會根據端點網址中的區域，決定處理要求的位置。系統會忽略資源路徑中任何衝突的位置。
控制台
如要使用 Google Cloud 控制台傳送多模態提示，請按照下列步驟操作：前往 Google Cloud 控制台「Agent Platform」部分的「Agent Studio」頁面。
按一下「建立提示」。
選用步驟：設定模型和參數：
- 模型：選取模型。
選用步驟：如要設定進階參數，請按一下「Advanced」(進階)，然後按照下列指示操作：
按一下即可展開進階設定
Top-K：使用滑桿或文字方塊輸入 Top-K 值。
「Top-K」會影響模型選取輸出符記的方式。如果 Top-K 設為1，代表下一個所選詞元是模型詞彙表的所有詞元中可能性最高者 (也稱為「貪婪解碼」)。如果 Top-K 設為3，則代表模型會依據溫度參數，從可能性最高的 3 個詞元中選取下一個詞元。在每個符記選取步驟中，模型會對機率最高的「Top-K」符記取樣，接著進一步根據「Top-P」篩選詞元，最後依 temperature 選出最終詞元。
如要取得較不隨機的回覆，請指定較低的值；如要取得較隨機的回覆，請調高此值。
- Top-P：使用滑桿或文字方塊輸入 Top-P 值。
模型會按照可能性最高到最低的順序選取詞元，直到所選詞元的可能性總和等於 Top-P 值。如要讓結果的變化性降到最低，請將 Top-P 設為
0。 - 回覆數量上限：使用滑桿或文字方塊，輸入要生成的回覆數量。
- 串流回覆：啟用後，系統會顯示正在生成的回覆。
- 安全篩選器門檻：選取看見可能有害回應的機率門檻。
- 啟用建立基準：多模態提示不支援建立基準。
- Region (區域)：選取要使用的區域。
- 溫度：使用滑桿或文字方塊輸入溫度值。
The temperature is used for sampling during response generation, which occurs whentopPandtopKare applied. Temperature controls the degree of randomness in token selection. Lower temperatures are good for prompts that require a less open-ended or creative response, while higher temperatures can lead to more diverse or creative results. A temperature of0means that the highest probability tokens are always selected. In this case, responses for a given prompt are mostly deterministic, but a small amount of variation is still possible.If the model returns a response that's too generic, too short, or the model gives a fallback response, try increasing the temperature. If the model enters infinite generation, increasing the temperature to at least
0.1may lead to improved results.1.0is the recommended starting value for temperature. </li> <li>**Output token limit**: Use the slider or textbox to enter a value for the max output limit. Maximum number of tokens that can be generated in the response. A token is approximately four characters. 100 tokens correspond to roughly 60-80 words.Specify a lower value for shorter responses and a higher value for potentially longer responses.
</li> <li>**Add stop sequence**: Optional. Enter a stop sequence, which is a series of characters that includes spaces. If the model encounters a stop sequence, the response generation stops. The stop sequence isn't included in the response, and you can add up to five stop sequences.</li> </ul>
按一下「插入媒體」，然後選取檔案來源。
上傳
選取要上傳的檔案，然後按一下「開啟」。
使用網址上傳
輸入要使用的檔案網址，然後按一下「插入」。
YouTube
輸入要使用的 YouTube 影片網址，然後按一下「Insert」(插入)。
您可以使用任何公開影片，或登入 Google Cloud 控制台的帳戶所擁有的影片。
Cloud Storage
依序選取 bucket 和要匯入的檔案，然後按一下「Select」(選取)。
Google 雲端硬碟
- 首次選取這個選項時，請選擇帳戶並授予 Agent Studio 存取權。您可以上傳多個檔案，總大小上限為 10 MB。單一檔案不得超過 7 MB。
- 按一下要新增的檔案。
按一下「選取」。
檔案縮圖會顯示在「提示詞」窗格中。系統也會顯示權杖總數。如果提示資料超出詞元限制，系統會截斷詞元，且不會納入處理資料。
在「提示」窗格中輸入文字提示詞。
選用：如要查看「Token ID to text」(詞元 ID 轉文字) 和「Token IDs」(詞元 ID)，請按一下「Prompt」(提示) 窗格中的「tokens count」(詞元數量)。
按一下「提交」。
選用：如要將提示詞儲存到「我的提示詞」，請依序點按 和「儲存」。
選用：如要取得提示的 Python 程式碼或 curl 指令，請依序點選 「Build with code」>「Get code」。
自訂影片處理
您可以在 Gemini for Google Cloud API 中自訂影片處理方式，例如設定剪輯間隔或提供自訂影格率取樣。
設定剪輯片段間隔
您可以指定 videoMetadata，並設定開始和結束偏移量，藉此剪輯影片。
設定自訂影格率
您可以將 fps 引數傳遞至
videoMetadata，設定自訂影格速率取樣。
根據預設，系統會從影片中每秒取樣 1 個影格 (FPS)。如果是長影片，建議設定較低的每秒影格數 (< 1)。這項功能特別適合用於靜態影片 (例如講座)。如要在快速變化的畫面中捕捉更多細節，建議設定較高的 FPS 值。
代理式影片解讀
代理式影片解讀功能可讓模型動態瀏覽影片內容，不必靜態處理每個影格。代理式影片解讀技術使用的詞元數量比靜態處理技術少，而且能提升回覆品質。這有助於降低成本，並加快長篇影片工作負載的回應速度。
您可以在同一個要求中，對不同影片使用代理式影片解讀和靜態處理。舉例來說，如果您有長篇影片 (例如一小時的講座) 和短篇影片內容 (例如 YouTube Shorts)，可以對長篇影片使用代理式影片理解功能，指定與情境相關的資訊，並對短篇影片內容使用靜態處理，達到影格層級的精確度。
對話過程中，影片內容必須保留。使用 GenerateContent API 進行代理處理時，回覆可能包含編碼影片內容的不透明步驟 (step_list)。您必須在下一個回合中加入這些步驟，以保留上下文。如果省略，影片脈絡就會遺失，模型也無法在不重新處理影片的情況下，回答後續問題。
支援的模型和檔案類型
下列模型支援代理式影片解讀功能：
按一下即可展開支援的模型
使用代理式影片解讀功能時，可採用下列來源：
- YouTube 網址
- Cloud Storage URI
- 內嵌 Base64 編碼的影片檔案
代理式影片解讀的使用時機
使用代理式影片理解功能 (media_processing = "AGENTIC") 執行下列工作負載：
- 長篇影片問答和搜尋：在長達一小時的講座、會議、錄製內容或教學影片中，提出特定問題或找出特定事件，不必以完整解析度將每個影格權杖化。
- 精細視覺檢查：放大較長影片中的特定時間戳記或視覺細節 (例如閱讀畫面上的小字、投影片或記分板變化)。
- 多影片比較：在單一要求中比較多部影片。在同一個要求中，您可以對每部影片使用不同的處理模式。
- 影片代理：建構代理，透過多輪對話支援推論影片內容。影片情境會在各回合之間保留，不需重新處理。
- 降低長影片工作負載的成本：如果長篇影片應用程式中只有部分片段與提示相關，可減少詞元用量。
在下列情況下，請保留預設的靜態處理 (media_processing = "STATIC")：
- 處理短片：如果是短片，靜態處理可避免多步驟工具導覽負擔，通常會使用較少的詞元，且延遲時間較短。
- 統一處理整部影片：工作負載需要對整個短片進行統一的逐格分析，而非針對特定片段進行檢查。
使用代理式影片解讀
您可以透過 GenerateContent API 使用代理式影片解讀功能。在要求中使用 media_processing =
"AGENTIC"：
Python
from google import genai
from google.genai import types
client = genai.Client()
# Example: Controlling media_processing explicitly
video_part = types.Part(
file_data=types.FileData(
file_uri="gs://my-bucket-name/sports_clip.mp4",
mime_type="video/mp4",
),
media_processing="agentic" # Options: "agentic", "static"
)
response = client.models.generate_content(
model="gemini-3.7-flash",
contents=[
video_part,
"Analyze the player's footwork right before the shot."
]
)
print(response.text)
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1beta1/projects/YOUR_PROJECT_ID/locations/global/publishers/google/models/gemini-3.7-flash:generateContent \
-d '{
"contents": [
{
"role": "USER",
"parts": [
{
"fileData": {
"mimeType": "video/mp4",
"fileUri": "gs://my-bucket/lecture.mp4"
},
"mediaProcessing": "AGENTIC"
},
{
"text": "Summarize the key takeaways."
}
]
}
],
"generationConfig": {
"thinkingLevel": "MEDIUM"
}
}'
根據預設，所有支援的模型都會將代理式影片解讀功能設為 STATIC 或停用。
調整媒體解析度
您可以調整 MediaResolution，使用較少的權杖處理影片。
設定選用模型參數
每個模型都有一組可設定的選用參數。詳情請參閱「內容生成參數」。
影片符記化
Gemini 3 的影片權杖化功能採用可變序列長度，取代舊版模型的平移和掃描方法，提升品質並降低延遲。
您可以為影片輸入內容指定媒體解析度，這會影響影片的詞元化方式，以及每部影片使用的詞元數量。您可以在 generationConfig 中設定 media_resolution，套用至要求中的所有媒體，也可以為個別媒體元件設定，覆寫頂層設定。影片的預設解析度為每影格 70 個詞元。
Gemini 3 模型支援下列解析度：
MEDIA_RESOLUTION_HIGH：每個影格 280 個詞元MEDIA_RESOLUTION_MEDIUM：每影格 70 個詞元MEDIA_RESOLUTION_LOW：每影格 70 個詞元MEDIA_RESOLUTION_UNSPECIFIED：每影格 70 個詞元 (預設)
如果是 Gemini 3 之前的模型，每個影格會以預設解析度 (每影格 258 個權杖) 或低解析度 (每影格 66 個權杖) 進行權杖化。
以下程式碼範例示範如何調整 media_resolution：
from google import genai from google.genai import types client = genai.Client() response = client.models.generate_content( model="gemini-3.1-pro-preview", contents=[ types.Part( file_data=types.FileData( file_uri="gs://cloud-samples-data/generative-ai/image/a-man-and-a-dog.png", mime_type="image/jpeg", ), media_resolution=types.PartMediaResolution( level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_HIGH ), ), Part( file_data=types.FileData( file_uri="gs://cloud-samples-data/generative-ai/video/behind_the_scenes_pixel.mp4", mime_type="video/mp4", ), media_resolution=types.PartMediaResolution( level=types.PartMediaResolutionLevel.MEDIA_RESOLUTION_LOW ), ), "When does the image appear in the video? What is the context?", ], ) print(response.text)
最佳做法
使用影片時，請遵循下列最佳做法和資訊，以獲得最佳效果：
- 如果提示詞包含單一影片，請將影片放在文字提示詞之前。
- 如需在有音訊的影片中加上時間戳記，請要求模型按照「時間戳記格式」一節所述的格式生成時間戳記。
如果是 Gemini 3 模型，也請考量下列事項：
- 如果影片需要精細的時間分析，例如快速動作理解或高速動作追蹤，請使用較高的每秒影格數 (FPS) 取樣率。
限制
雖然多模態版 Gemini 模型在許多多模態用途中都非常強大，但請務必瞭解模型的限制：
- 內容審核：如果影片違反安全政策，模型會拒絕提供答案。
- 非語音聲音辨識：支援音訊的模型可能會誤判非語音聲音。
影片技術詳細資料
File API 處理：使用 File API 時，影片會以每秒 1 影格 (FPS) 的頻率取樣，音訊則以 1 Kbps (單聲道) 的頻率處理。系統每秒都會新增時間戳記。
- 為提升推論成效，這些費率日後可能會有變動。
時間戳記格式：在提示中提及影片的特定時刻時，時間戳記格式取決於影片的每秒影格數 (FPS) 取樣率：
取樣率為 1 FPS 以下：請使用
MM:SS格式，前兩位數代表分鐘，後兩位數代表秒。如果時差超過 1 小時，請使用H:MM:SS格式。取樣率高於 1 FPS：請使用
MM:SS.sss格式，如果偏移量大於 1 小時，請使用H:MM:SS.sss格式，如下所示：- 第一個數字代表小時。
- 後兩位數字代表分鐘。
- 第三組兩位數代表秒。
- 最後三位數代表亞秒。
最佳做法：
為獲得最佳結果，請在每個提示要求中只使用一部影片。
如果結合文字和單一影片，請將文字提示詞放在
contents陣列中影片部分的後方。請注意，由於取樣率為 1 FPS，快速動作序列可能會遺失細節。如有需要，請考慮放慢這類片段。
後續步驟
- 開始使用多模態版 Gemini 建構內容：新客戶可獲得價值 $300 美元的免費 Google Cloud 抵免額，探索多模態版 Gemini 的功能。
- 瞭解如何傳送對話提示要求。
- 瞭解負責任的 AI 最佳做法和 Agent Platform 的安全篩選器。