媒體解析度¶
media_resolution 參數決定 Gemini API 處理影像、影片、音訊與 PDF 文件等媒體輸入的方式,透過設定配置給媒體輸入的權杖數量上限,讓你在回應品質、延遲與成本之間取得平衡。視覺與文件輸入的權杖配置會依解析度設定縮放;音訊輸入則在所有解析度等級下,都以每秒固定速率進行權杖化。各設定的預設值與對應的權杖數,請參閱權杖數量一節。
你可以針對請求中的個別媒體物件(內容項目)設定媒體解析度(Gemini 4 與 Gemini 3 模型)。
逐內容項目的媒體解析度(Gemini 4 與 Gemini 3 模型)¶
Gemini 4 與 Gemini 3 模型可讓你為請求中的個別媒體物件設定媒體解析度,藉此精細地最佳化權杖用量。同一個請求中可以混用不同解析度等級,例如對複雜圖表使用高解析度、對簡單的情境圖片使用低解析度。
from google import genai
client = genai.Client()
myfile = client.files.upload(file="path/to/image.jpg")
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input=[
{"type": "text", "text": "Describe this image:"},
{
"type": "image",
"uri": myfile.uri,
"mime_type": myfile.mime_type,
"resolution": "high"
}
]
)
print(interaction.output_text)
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const myfile = await ai.files.upload({
file: "path/to/image.jpg",
config: { mimeType: "image/jpeg" },
});
const interaction = await ai.interactions.create({
model: "gemini-4-hydrogen",
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();
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-4-hydrogen"))
.input(InteractionsInput.ofContent(contents))
.build();
Interaction interaction =
client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
System.out.println(interaction.outputText().orElse(""));
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-4-hydrogen"),
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)
}
}
# 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' \
-H "Api-Revision: 2026-05-20" \
-d '{
"model": "gemini-4-hydrogen",
"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 + Native Text |
medium |
560 | 70 | 25(每秒) | 560 + Native Text |
high |
1120 | 280 | 25(每秒) | 1120 + Native Text |
ultra_high |
2240 | N/A | N/A | N/A |
選擇合適的解析度¶
- 預設值(
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 控制每個畫格的權杖預算,而 processing 模式則控制載入影片中的哪些內容。這兩項設定彼此獨立:無論是靜態處理或代理式影片理解,都可以搭配低、中或高解析度使用。詳情請參閱代理式影片理解。
版本相容性摘要¶
- 在個別內容項目上設定
resolution,支援 Gemini 4 與 Gemini 3 模型。