Resolusi media

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 mengetahui setelan yang berbeda, nilai default, dan korespondensinya dengan token, lihat bagian Jumlah token.

Anda dapat mengonfigurasi resolusi media untuk setiap objek media (item konten) dalam permintaan Anda (khusus Gemini 3).

Resolusi media per item konten (khusus Gemini 3)

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.

from google import genai
from google.genai import types

client = genai.Client()

myfile = client.files.upload(file="path/to/image.jpg")

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "text", "text": "Describe this image:"},
        {
            "type": "image",
            "uri": myfile.uri,
            "mime_type": myfile.mime_type,
            "resolution": "high"
        }
    ]
)
print(interaction.steps[-1].content[0].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-3-flash-preview",
    input: [
      { type: "text", text: "Describe this image:" },
      {
        type: "image",
        uri: myfile.uri,
        mimeType: myfile.mimeType,
        resolution: "high"
      }
    ],
  });
  console.log(interaction.steps.at(-1).content[0].text);
}

await main();

# 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-flash-preview",
    "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 tingkat resolusi media berikut:

• unspecified: Setelan default. Jumlah token untuk tingkat ini sangat bervariasi antara Gemini 3 dan model Gemini sebelumnya.
• low: Jumlah token lebih rendah, sehingga menghasilkan pemrosesan yang lebih cepat dan biaya yang lebih rendah, tetapi dengan detail yang lebih sedikit.
• medium: Keseimbangan antara detail, biaya, dan latensi.
• high: Jumlah token lebih tinggi, memberikan lebih banyak detail untuk digunakan model, dengan mengorbankan peningkatan latensi dan biaya.
• ultra_high (Khusus per item konten): Jumlah token tertinggi, diperlukan untuk kasus penggunaan tertentu seperti penggunaan komputer.

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

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

Memilih resolusi yang tepat

• Default (unspecified): Mulai dengan setelan default. Setelan ini disesuaikan 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 mendetail 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, 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 dibandingkan high.
• Kontrol per item konten (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 Anda untuk menemukan kompromi terbaik antara kualitas, latensi, dan biaya.

Ringkasan kompatibilitas versi

• Menetapkan resolution pada setiap item konten khusus untuk model Gemini 3.

Langkah berikutnya

• Pelajari lebih lanjut kemampuan multimodal Gemini API dalam panduan pemahaman gambar, pemahaman video, dan pemahaman dokumen.