Parameter media_resolution mengontrol cara Gemini API memproses input media seperti gambar, video, dan dokumen PDF dengan menentukan jumlah token maksimum yang dialokasikan untuk input media, sehingga Anda dapat menyeimbangkan kualitas respons dengan latensi dan biaya. Untuk setelan yang berbeda, nilai default, dan cara nilai tersebut sesuai dengan token, lihat bagian Jumlah token.
Anda dapat mengonfigurasi resolusi media dengan dua cara:
Per bagian (khusus Gemini 3)
Secara global untuk seluruh permintaan
generateContent(semua model multimodal)
Resolusi media per bagian (khusus Gemini 3)
Gemini 3 memungkinkan Anda menetapkan resolusi media untuk setiap objek media dalam permintaan, sehingga menawarkan pengoptimalan penggunaan token yang terperinci. Anda dapat menggabungkan tingkat resolusi dalam satu permintaan. Misalnya, menggunakan resolusi tinggi untuk diagram yang kompleks dan resolusi rendah untuk gambar kontekstual yang sederhana. Setelan ini menggantikan konfigurasi global untuk bagian tertentu. Untuk setelan default, lihat bagian Jumlah token.
Python
from google import genai
from google.genai import types
# The media_resolution parameter for parts is currently only available in the v1alpha API version. (experimental)
client = genai.Client(
http_options={
'api_version': 'v1alpha',
}
)
# Replace with your image data
with open('path/to/image1.jpg', 'rb') as f:
image_bytes_1 = f.read()
# Create parts with different resolutions
image_part_high = types.Part.from_bytes(
data=image_bytes_1,
mime_type='image/jpeg',
media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH
)
model_name = 'gemini-3-pro-preview'
response = client.models.generate_content(
model=model_name,
contents=["Describe these images:", image_part_high]
)
print(response.text)
JavaScript
// Example: Setting per-part media resolution in JavaScript
import { GoogleGenAI, MediaResolution, Part } from '@google/genai';
import * as fs from 'fs';
import { Buffer } from 'buffer'; // Node.js
const ai = new GoogleGenAI({ httpOptions: { apiVersion: 'v1alpha' } });
// Helper function to convert local file to a Part object
function fileToGenerativePart(path, mimeType, mediaResolution) {
return {
inlineData: { data: Buffer.from(fs.readFileSync(path)).toString('base64'), mimeType },
mediaResolution: { 'level': mediaResolution }
};
}
async function run() {
// Create parts with different resolutions
const imagePartHigh = fileToGenerativePart('img.png', 'image/png', Part.MediaResolutionLevel.MEDIA_RESOLUTION_HIGH);
const model_name = 'gemini-3-pro-preview';
const response = await ai.models.generateContent({
model: model_name,
contents: ['Describe these images:', imagePartHigh]
// Global config can still be set, but per-part settings will override
// config: {
// mediaResolution: MediaResolution.MEDIA_RESOLUTION_MEDIUM
// }
});
console.log(response.text);
}
run();
REST
# Replace with paths to your images
IMAGE_PATH="path/to/image.jpg"
# Base64 encode the images
BASE64_IMAGE1=$(base64 -w 0 "$IMAGE_PATH")
MODEL_ID="gemini-3-pro-preview"
echo '{
"contents": [{
"parts": [
{"text": "Describe these images:"},
{
"inline_data": {
"mime_type": "image/jpeg",
"data": "'"$BASE64_IMAGE1"'",
},
"media_resolution": {"level": "MEDIA_RESOLUTION_HIGH"}
}
]
}]
}' > request.json
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1alpha/models/${MODEL_ID}:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json
Resolusi media global
Anda dapat menetapkan resolusi default untuk semua bagian media dalam permintaan menggunakan
GenerationConfig. Fitur ini didukung oleh semua model multimodal. Jika permintaan
mencakup setelan global dan per bagian, setelan per bagian akan diprioritaskan untuk item tertentu tersebut.
Python
from google import genai
from google.genai import types
client = genai.Client()
# Prepare standard image part
with open('image.jpg', 'rb') as f:
image_bytes = f.read()
image_part = types.Part.from_bytes(data=image_bytes, mime_type='image/jpeg')
# Set global configuration
config = types.GenerateContentConfig(
media_resolution=types.MediaResolution.MEDIA_RESOLUTION_HIGH
)
response = client.models.generate_content(
model='gemini-2.5-flash',
contents=["Describe this image:", image_part],
config=config
)
print(response.text)
JavaScript
import { GoogleGenAI, MediaResolution } from '@google/genai';
import * as fs from 'fs';
const ai = new GoogleGenAI({ });
async function run() {
// ... (Image loading logic) ...
const response = await ai.models.generateContent({
model: 'gemini-2.5-flash',
contents: ["Describe this image:", imagePart],
config: {
mediaResolution: MediaResolution.MEDIA_RESOLUTION_HIGH
}
});
console.log(response.text);
}
run();
REST
# ... (Base64 encoding logic) ...
curl -s -X POST \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [...],
"generation_config": {
"media_resolution": "MEDIA_RESOLUTION_HIGH"
}
}'
Nilai resolusi yang tersedia
Gemini API menentukan tingkat berikut untuk resolusi media:
MEDIA_RESOLUTION_UNSPECIFIED: Setelan default. Jumlah token untuk level ini sangat bervariasi antara Gemini 3 dan model Gemini sebelumnya.MEDIA_RESOLUTION_LOW: Jumlah token yang lebih rendah, sehingga pemrosesan lebih cepat dan biaya lebih rendah, tetapi dengan detail yang lebih sedikit.MEDIA_RESOLUTION_MEDIUM: Keseimbangan antara detail, biaya, dan latensi.MEDIA_RESOLUTION_HIGH: Jumlah token yang lebih tinggi, memberikan lebih banyak detail untuk dikerjakan model, dengan mengorbankan peningkatan latensi dan biaya.- (Segera hadir)
MEDIA_RESOLUTION_ULTRA_HIGH: Jumlah token tertinggi yang diperlukan untuk kasus penggunaan tertentu seperti penggunaan komputer.
Jumlah token yang dihasilkan untuk setiap tingkat ini bergantung pada jenis media (Gambar, Video, 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 3
| MediaResolution | Gambar | Video | |
MEDIA_RESOLUTION_UNSPECIFIED (Default)
|
1120 | 70 | 560 |
MEDIA_RESOLUTION_LOW
|
280 | 70 | 280 + Teks Native |
MEDIA_RESOLUTION_MEDIUM
|
560 | 70 | 560 + Native Text |
MEDIA_RESOLUTION_HIGH
|
1120 | 280 | 1120 + Teks Native |
Model Gemini 2.5
| MediaResolution | Gambar | Video | PDF (Dipindai) | PDF (Native) |
MEDIA_RESOLUTION_UNSPECIFIED (Default)
|
256 + Pan & Scan (~2048) | 256 | 256 + OCR | 256 + Teks Native |
MEDIA_RESOLUTION_LOW
|
64 | 64 | 64 + OCR | 64 + Teks Native |
MEDIA_RESOLUTION_MEDIUM
|
256 | 256 | 256 + OCR | 256 + Teks Native |
MEDIA_RESOLUTION_HIGH
|
256 + Pan & Scan | 256 | 256 + OCR | 256 + Teks Native |
Memilih resolusi yang tepat
- Default (
UNSPECIFIED): Mulai dengan default. Model ini disetel untuk memberikan keseimbangan yang baik antara kualitas, latensi, dan biaya untuk kasus penggunaan yang paling umum. LOW: Gunakan untuk skenario yang mengutamakan biaya dan latensi, serta detail yang lebih mendalam kurang penting.MEDIUM/HIGH: Tingkatkan resolusi saat tugas memerlukan pemahaman detail rumit dalam media. Hal ini sering kali diperlukan untuk analisis visual yang kompleks, membaca diagram, atau memahami dokumen yang padat.- Kontrol per bagian (Gemini 3): Manfaatkan fitur ini untuk 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 setelan resolusi media yang direkomendasikan untuk setiap jenis media yang didukung.
| Jenis Media | Setelan yang Direkomendasikan | Token Maksimal | Panduan Penggunaan |
| Gambar | MEDIA_RESOLUTION_HIGH
|
1120 | Direkomendasikan untuk sebagian besar tugas analisis gambar guna memastikan kualitas maksimum. |
MEDIA_RESOLUTION_MEDIUM
|
560 | Optimal untuk pemahaman dokumen; kualitas biasanya mencapai titik jenuh pada medium. Meningkatkan ke high jarang meningkatkan hasil OCR untuk dokumen standar.
|
|
| Video (Umum) | MEDIA_RESOLUTION_LOW (atau MEDIA_RESOLUTION_MEDIUM)
|
70 (per frame) | Catatan: Untuk video, setelan low dan medium diperlakukan sama (70 token) untuk mengoptimalkan penggunaan konteks. Langkah ini cukup untuk sebagian besar tugas pengenalan dan deskripsi tindakan.
|
| Video (Banyak teks) | MEDIA_RESOLUTION_HIGH
|
280 (per frame) | Diperlukan hanya jika kasus penggunaan melibatkan pembacaan teks padat (OCR) atau detail kecil dalam frame video. |
Selalu uji dan evaluasi dampak setelan resolusi yang berbeda pada aplikasi spesifik Anda untuk menemukan kompromi terbaik antara kualitas, latensi, dan biaya.
Ringkasan kompatibilitas versi
- Enum
MediaResolutiontersedia untuk semua model yang mendukung input media. - Jumlah token yang terkait dengan setiap tingkat enum berbeda antara model Gemini 3 dan versi Gemini sebelumnya.
- Menetapkan
media_resolutionpada masing-masing objekParteksklusif untuk model Gemini 3.
Langkah berikutnya
- Pelajari lebih lanjut kemampuan multimodal Gemini API dalam panduan pemahaman gambar, pemahaman video, dan pemahaman dokumen.