Resolusi media

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 ditokenisasi dengan 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 dengan dua cara:

• Per bagian (model Gemini 4 dan Gemini 3)

• Secara global untuk seluruh permintaan generateContent (semua model multimodal)

Resolusi media per bagian (Gemini 4 dan Gemini 3)

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. Setelan ini mengganti konfigurasi global apa pun untuk bagian tertentu. Untuk setelan default, lihat bagian Jumlah token.

from google import genai
from google.genai import types

# The media_resolution parameter for parts is available in the v1beta API version.
client = genai.Client(
  http_options={
      'api_version': 'v1beta',
  }
)

# 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-4-argon'

response = client.models.generate_content(
    model=model_name,
    contents=["Describe these images:", image_part_high]
)
print(response.text)

// 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: 'v1beta' } });

// 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-4-argon';
    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();

# 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-4-argon"

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/v1beta/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. Hal ini didukung oleh semua model multimodal. Jika permintaan menyertakan setelan global dan setelan per bagian, setelan per bagian akan diprioritaskan untuk item tertentu tersebut.

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-3.8-flash',
    contents=["Describe this image:", image_part],
    config=config
)
print(response.text)

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-3.8-flash',
      contents: ["Describe this image:", imagePart],
      config: {
         mediaResolution: MediaResolution.MEDIA_RESOLUTION_HIGH
      }
   });
   console.log(response.text);
}
run();

# ... (Base64 encoding logic) ...

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-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 level berikut untuk resolusi media:

• MEDIA_RESOLUTION_UNSPECIFIED: Setelan default. Jumlah token untuk tingkat ini sangat bervariasi antara Gemini 3 dan model Gemini sebelumnya.
• MEDIA_RESOLUTION_LOW: Jumlah token yang lebih rendah, sehingga menghasilkan pemrosesan yang lebih cepat dan biaya yang 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, yang memberikan lebih banyak detail untuk digunakan model, dengan konsekuensi peningkatan latensi dan biaya.
• MEDIA_RESOLUTION_ULTRA_HIGH (Per bagian saja): Jumlah token tertinggi, diperlukan untuk kasus penggunaan tertentu seperti penggunaan komputer.

Perhatikan bahwa MEDIA_RESOLUTION_HIGH memberikan performa optimal untuk sebagian besar kasus penggunaan.

Jumlah pasti token yang dihasilkan untuk setiap level 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 3

Model Gemini 2.5

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 saat biaya dan latensi sangat penting, dan detail yang akurat kurang penting.
• MEDIUM / HIGH: Tingkatkan resolusi saat tugas memerlukan pemahaman detail yang rumit dalam media. Hal ini sering kali diperlukan untuk analisis visual yang kompleks, membaca diagram, atau memahami dokumen yang padat.
• ULTRA HIGH - Hanya tersedia untuk setelan per bagian. Direkomendasikan untuk kasus penggunaan tertentu seperti penggunaan komputer atau saat pengujian menunjukkan peningkatan yang jelas dibandingkan HIGH.
• Kontrol per bagian (Gemini 4 dan Gemini 3): Mengoptimalkan penggunaan token. Misalnya, dalam perintah dengan beberapa gambar, gunakan HIGH untuk diagram yang kompleks dan LOW atau MEDIUM untuk gambar kontekstual yang lebih sederhana.

Setelan yang direkomendasikan

Berikut adalah setelan resolusi media yang direkomendasikan untuk setiap jenis media yang didukung.

Selalu uji dan evaluasi dampak setelan resolusi yang berbeda pada aplikasi spesifik 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_resolution mengontrol resolusi setiap frame (jumlah token per frame).
• processing / media_processing mengontrol 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 agentic.

Ringkasan kompatibilitas versi

• Enum MediaResolution tersedia untuk semua model yang mendukung input media.
• Jumlah token yang terkait dengan setiap level enum berbeda antara model Gemini 4 / Gemini 3 dan versi Gemini sebelumnya.
• Setelan media_resolution pada setiap objek Part 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.