media_resolution 參數會決定分配給媒體輸入內容的權杖數量上限，藉此控制 Gemini API 處理圖片、影片、音訊和 PDF 文件等媒體輸入內容的方式，讓您在回覆品質、延遲時間和成本之間取得平衡。視覺和文件輸入內容會根據解析度設定調整權杖分配，但音訊輸入內容在所有解析度層級中，每秒的權杖化率都是固定的。如要瞭解不同設定的預設值，以及這些設定如何對應至權杖，請參閱「權杖計數」一節。
您可以為要求中的個別媒體物件 (內容項目) 設定媒體解析度 (Gemini 4 和 Gemini 3 模型)。
每項內容的媒體解析度 (Gemini 4 和 Gemini 3 模型)
Gemini 4 和 Gemini 3 模型可讓您在要求中為個別媒體物件設定媒體解析度，進而精細調整權杖用量。您可以在單一要求中混用解析度等級。例如，複雜的圖表使用高解析度，簡單的情境圖片則使用低解析度。
Python
from google import genai
client = genai.Client()
myfile = client.files.upload(file="path/to/image.jpg")
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=[
{"type": "text", "text": "Describe this image:"},
{
"type": "image",
"uri": myfile.uri,
"mime_type": myfile.mime_type,
"resolution": "high"
}
]
)
print(interaction.output_text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const myfile = await ai.files.upload({
file: "path/to/image.jpg",
config: { mime_type: "image/jpeg" },
});
const interaction = await ai.interactions.create({
model: "gemini-3.8-flash",
input: [
{ type: "text", text: "Describe this image:" },
{
type: "image",
uri: myfile.uri,
mime_type: myfile.mimeType,
resolution: "high"
}
],
});
console.log(interaction.output_text);
}
await main();
Java
import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;
Client client = new Client();
Content textContent = TextContent.builder().text("Describe the details in this high-resolution image.").build();
Content imageContent =
ImageContent.builder()
.uri("gs://cloud-samples-data/generative-ai/image/scones.jpg")
.mimeType(ImageContentMimeType.IMAGE_JPEG)
.build();
List<Content> contents = Arrays.asList(textContent, imageContent);
CreateModelInteraction params =
CreateModelInteraction.builder()
.model(Model.of("gemini-3.8-flash"))
.input(InteractionsInput.ofContent(contents))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
Go
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
"google.golang.org/genai/interactions/models/interactions"
"google.golang.org/genai/interactions/models/operations"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, nil)
if err != nil {
log.Fatal(err)
}
uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/image.jpg", nil)
if err != nil {
log.Fatal(err)
}
res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
Model: interactions.Model("gemini-3.8-flash"),
Input: interactions.NewInteractionsInput([]interactions.Content{
interactions.NewContent(interactions.TextContent{
Text: "Describe the details in this high-resolution image.",
}),
interactions.NewContent(interactions.ImageContent{
URI: genai.Ptr(uploadedFile.URI),
MimeType: interactions.ImageContentMimeType(uploadedFile.MIMEType).ToPointer(),
Resolution: interactions.MediaResolutionHigh.ToPointer(),
}),
}),
}),
})
if err != nil {
log.Fatal(err)
}
if res.Interaction.OutputText != nil {
fmt.Println(*res.Interaction.OutputText)
}
}
REST
# First upload the file using the Files API, then use the URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-3.8-flash",
"input": [
{"type": "text", "text": "Describe this image:"},
{
"type": "image",
"uri": "YOUR_FILE_URI",
"mime_type": "image/jpeg",
"resolution": "high"
}
]
}'
可用的解析度值
Gemini API 定義了下列媒體解析度等級：
unspecified：預設設定。Gemini 4/3 和舊版 Gemini 模型之間，這個層級的權杖數差異很大。low：詞元數較少，處理速度較快且成本較低，但細節較少。medium：在詳細程度、成本和延遲時間之間取得平衡。high：代幣數量較多，可為模型提供更多詳細資料，但會增加延遲時間和成本。ultra_high(僅限每個內容項目)：詞元數最高，適用於電腦使用等特定用途。
請注意，high 可為大多數用途提供最佳效能。
每個層級產生的確切權杖數量取決於媒體類型 (圖片、影片、音訊、PDF) 和模型版本。
詞元數
下表列出各模型系列中，每個 media_resolution 值和媒體類型的約略詞元數。
Gemini 4 和 Gemini 3 模型
| MediaResolution | 圖片 | 影片 | 音訊 | |
|---|---|---|---|---|
unspecified (預設) |
1120 | 70 | 25 (每秒) | 560 |
low |
280 | 70 | 25 (每秒) | 280 + 原生文字 |
medium |
560 | 70 | 25 (每秒) | 560 + 原生文字 |
high |
1120 | 280 | 25 (每秒) | 1120 + 原生文字 |
ultra_high |
2240 | 不適用 | 不適用 | 不適用 |
選擇合適的解析度
- 預設 (
unspecified)：從預設值開始。經過調整，可在品質、延遲時間和成本之間取得良好平衡，適合大多數常見用途。 low：適用於成本和延遲時間至關重要，但細節精確度較不重要的情境。medium/high：如果工作需要理解媒體中的複雜細節，請提高解析度。這項功能通常用於複雜的視覺分析、圖表解讀或理解密集文件。ultra_high- 僅適用於每個內容項目的設定。建議用於特定用途，例如使用電腦，或測試結果顯示效果明顯優於high。- 依內容項目控管 (Gemini 4 和 Gemini 3)：盡量減少權杖用量。舉例來說，如果提示中有多張圖片，請使用
high處理複雜圖表，並使用low或medium處理較簡單的背景圖片。
建議設定
以下列出各支援媒體類型的建議媒體解析度設定。
| 媒體類型 | 建議設定 | 詞元數上限 | 使用指南 |
|---|---|---|---|
| 圖片 | high |
1120 | 建議用於大多數圖像分析工作，確保最高品質。 |
medium |
560 | 最適合用於文件解讀，品質通常會在 medium 達到飽和。增加至 high 很少能改善標準文件的 OCR 結果。 |
|
| 影片 (一般) | low (或 medium) |
70 (每影格) | 注意：對於影片，系統會將 low 和 medium 設定視為相同 (70 個權杖)，以盡量使用情境資訊。這足以應付大多數動作辨識和描述工作。 |
| 影片 (文字較多) | high |
280 (每個影格) | 只有在用途涉及讀取影片影格中的密集文字 (OCR) 或微小細節時，才需要提供。 |
| 音訊 | unspecified (預設) |
25 (每秒) | 在所有支援的解析度設定 (unspecified、low、medium 和 high) 下，音訊會以每秒 25 個詞元的固定速率轉換為詞元。 |
請務必測試及評估不同解析度設定對應用程式的影響，在品質、延遲時間和成本之間取得最佳平衡。
與影片處理模式的關係
media_resolution 和處理參數可控制影片輸入的不同層面：
media_resolution控制每個影格的解析度 (每個影格的權杖數量)。processing/media_processing控制項會將影片中的哪些內容載入至環境。
你可以在同一個影片輸入上設定這兩項。舉例來說，您可能會使用代理處理程序和低媒體解析度，盡量減少長影片的權杖總用量。
如要瞭解影片處理模式的詳細資訊，請參閱「代理式影片解讀」指南。
版本相容性摘要
- Gemini 4 和 Gemini 3 模型支援為個別內容項目設定
resolution。