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

Anda dapat mengonfigurasi resolusi media dengan dua cara:

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 PDF
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 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.

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.
PDF 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 MediaResolution tersedia 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_resolution pada masing-masing objek Part eksklusif untuk model Gemini 3.

Langkah berikutnya