Parameter media_resolution mengontrol cara Gemini API memproses input media seperti gambar, video, audio, dan dokumen PDF dengan menentukan jumlah token maksimum yang dialokasikan untuk input media, sehingga Anda dapat menyeimbangkan kualitas respons dengan latensi dan biaya. Meskipun input visual dan dokumen menskalakan alokasi token berdasarkan setelan resolusi, input audio di-tokenisasi pada kecepatan tetap per detik di semua tingkat resolusi. Untuk
setelan yang berbeda, nilai default, dan cara nilai tersebut sesuai dengan token, lihat bagian
Jumlah token.
Anda dapat mengonfigurasi resolusi media untuk setiap objek media (item konten) dalam permintaan Anda (model Gemini 4 dan Gemini 3).
Resolusi media per item konten (model Gemini 4 dan Gemini 3)
Model Gemini 4 dan Gemini 3 memungkinkan Anda menetapkan resolusi media untuk setiap objek media dalam permintaan Anda, sehingga menawarkan pengoptimalan penggunaan token yang mendetail. Anda dapat menggabungkan tingkat resolusi dalam satu permintaan. Misalnya, menggunakan resolusi tinggi untuk diagram yang kompleks dan resolusi rendah untuk gambar kontekstual yang sederhana.
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"
}
]
}'
Nilai resolusi yang tersedia
Gemini API menentukan level berikut untuk resolusi media:
unspecified: Setelan default. Jumlah token untuk level ini bervariasi secara signifikan antara Gemini 4/3 dan model Gemini sebelumnya.low: Jumlah token lebih rendah, sehingga pemrosesan lebih cepat dan biaya lebih rendah, tetapi dengan detail yang lebih sedikit.medium: Keseimbangan antara detail, biaya, dan latensi.high: Jumlah token yang lebih tinggi, yang memberikan lebih banyak detail untuk diproses model, dengan konsekuensi peningkatan latensi dan biaya.ultra_high(Hanya per item konten): Jumlah token tertinggi, diperlukan untuk kasus penggunaan tertentu seperti penggunaan komputer.
Perhatikan bahwa high memberikan performa yang optimal untuk sebagian besar kasus penggunaan.
Jumlah token yang dihasilkan untuk setiap tingkat ini bergantung pada jenis media (Gambar, Video, Audio, PDF) dan versi model.
Jumlah token
Tabel di bawah merangkum perkiraan jumlah token untuk setiap nilai media_resolution dan jenis media per kelompok model.
Model Gemini 4 dan Gemini 3
| MediaResolution | Gambar | Video | Audio | |
|---|---|---|---|---|
unspecified (Default) |
1120 | 70 | 25 (per detik) | 560 |
low |
280 | 70 | 25 (per detik) | 280 + Teks Bawaan |
medium |
560 | 70 | 25 (per detik) | 560 + Teks Bawaan |
high |
1120 | 280 | 25 (per detik) | 1120 + Native Text |
ultra_high |
2240 | T/A | T/A | T/A |
Memilih resolusi yang tepat
- Default (
unspecified): Mulai dengan default. Model ini disetel untuk keseimbangan kualitas, latensi, dan biaya yang baik untuk sebagian besar kasus penggunaan umum. low: Gunakan untuk skenario saat biaya dan latensi sangat penting, dan detail yang mendetail kurang penting.medium/high: Tingkatkan resolusi saat tugas memerlukan pemahaman detail yang rumit dalam media. Hal ini sering diperlukan untuk analisis visual yang kompleks, pembacaan diagram, atau pemahaman dokumen yang padat.ultra_high- Hanya tersedia untuk setelan per item konten. Direkomendasikan untuk kasus penggunaan tertentu seperti penggunaan komputer atau saat pengujian menunjukkan peningkatan yang jelas dibandingkanhigh.- Kontrol per item konten (Gemini 4 dan Gemini 3): Mengoptimalkan penggunaan token. Misalnya, dalam perintah dengan beberapa gambar, gunakan
highuntuk diagram yang kompleks danlowataumediumuntuk gambar kontekstual yang lebih sederhana.
Setelan yang direkomendasikan
Berikut adalah daftar setelan resolusi media yang direkomendasikan untuk setiap jenis media yang didukung.
| Jenis Media | Setelan yang Direkomendasikan | Token Maksimum | Panduan Penggunaan |
|---|---|---|---|
| Gambar | high |
1120 | Direkomendasikan untuk sebagian besar tugas analisis gambar guna memastikan kualitas maksimum. |
medium |
560 | Optimal untuk pemahaman dokumen; kualitas biasanya jenuh pada medium. Meningkatkan ke high jarang meningkatkan hasil OCR untuk dokumen standar. |
|
| Video (Umum) | low (atau medium) |
70 (per frame) | Catatan: Untuk video, setelan low dan medium diperlakukan sama (70 token) untuk mengoptimalkan penggunaan konteks. Hal ini sudah cukup untuk sebagian besar tugas pengenalan dan deskripsi tindakan. |
| Video (Banyak teks) | high |
280 (per frame) | Hanya diperlukan jika kasus penggunaan melibatkan pembacaan teks padat (OCR) atau detail kecil dalam frame video. |
| Audio | unspecified (Default) |
25 (per detik) | Audio ditokenisasi dengan kecepatan tetap 25 token per detik di semua setelan resolusi yang didukung (unspecified, low, medium, dan high). |
Selalu uji dan evaluasi dampak berbagai setelan resolusi pada aplikasi Anda untuk menemukan kompromi terbaik antara kualitas, latensi, dan biaya.
Hubungan dengan mode pemrosesan video
Parameter media_resolution dan pemrosesan mengontrol berbagai aspek input video:
media_resolutionmengontrol resolusi setiap frame (jumlah token per frame).processing/media_processingmengontrol konten mana dari video yang dimuat ke dalam konteks.
Anda dapat menyetel keduanya pada input video yang sama. Misalnya, Anda dapat menggunakan pemrosesan agentic dengan resolusi media rendah untuk meminimalkan total penggunaan token untuk video panjang.
Untuk mengetahui detail tentang mode pemrosesan video, lihat panduan Pemahaman video agentik.
Ringkasan kompatibilitas versi
- Menetapkan
resolutionpada setiap item konten didukung di model Gemini 4 dan Gemini 3.
Langkah berikutnya
- Pelajari lebih lanjut kemampuan multimodal Gemini API dalam panduan pemahaman gambar, pemahaman video, pemahaman audio, dan pemahaman dokumen.