Medya çözünürlüğü

media_resolution parametresi, medya girişleri için ayrılan maksimum jeton sayısını belirleyerek Gemini API'nin resim, video ve PDF belgeleri gibi medya girişlerini nasıl işlediğini kontrol eder. Bu sayede yanıt kalitesini gecikme ve maliyetle dengelemenizi sağlar. Farklı ayarlar, varsayılan değerler ve bunların jetonlarla nasıl eşleştiği hakkında bilgi edinmek için Jeton sayıları bölümüne bakın.

Medya çözünürlüğünü iki şekilde yapılandırabilirsiniz:

Bölüm başına medya çözünürlüğü (yalnızca Gemini 3)

Gemini 3, isteğinizdeki her bir medya nesnesi için medya çözünürlüğünü ayarlamanıza olanak tanır ve jeton kullanımında ayrıntılı optimizasyon sunar. Tek bir istekte çözünürlük düzeylerini karıştırabilirsiniz. Örneğin, karmaşık bir şema için yüksek çözünürlük, basit bir bağlamsal resim için ise düşük çözünürlük kullanabilirsiniz. Bu ayar, belirli bir bölüm için tüm genel yapılandırmaları geçersiz kılar. Varsayılan ayarlar için Jeton sayıları bölümüne bakın.

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

Genel medya çözünürlüğü

GenerationConfig kullanarak bir istekteki tüm medya bölümleri için varsayılan çözünürlük ayarlayabilirsiniz. Bu özellik tüm çok formatlı modellerde desteklenir. Bir istek hem genel hem de parça başına ayarları içeriyorsa söz konusu öğe için parça başına ayar öncelikli olur.

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"
    }
  }'

Kullanılabilir çözünürlük değerleri

Gemini API, medya çözünürlüğü için aşağıdaki düzeyleri tanımlar:

  • MEDIA_RESOLUTION_UNSPECIFIED: Varsayılan ayardır. Bu seviyenin jeton sayısı, Gemini 3 ile önceki Gemini modelleri arasında önemli ölçüde farklılık gösterir.
  • MEDIA_RESOLUTION_LOW: Daha düşük jeton sayısı, daha hızlı işlem ve daha düşük maliyet sağlar ancak daha az ayrıntı içerir.
  • MEDIA_RESOLUTION_MEDIUM: Ayrıntı, maliyet ve gecikme arasında bir denge.
  • MEDIA_RESOLUTION_HIGH: Daha yüksek jeton sayısı, gecikme süresinin ve maliyetin artması karşılığında modelin çalışması için daha fazla ayrıntı sağlar.
  • (Yakında kullanıma sunulacak) MEDIA_RESOLUTION_ULTRA_HIGH: Bilgisayar kullanımı gibi belirli kullanım alanları için gereken en yüksek jeton sayısı.

Bu seviyelerin her biri için oluşturulan jetonların tam sayısı hem medya türüne (resim, video, PDF) hem de model sürümüne bağlıdır.

Jeton sayıları

Aşağıdaki tablolarda, her model ailesi için media_resolution değerine ve medya türüne göre yaklaşık jeton sayıları özetlenmektedir.

Gemini 3 Modelleri

MediaResolution Resim Video PDF
MEDIA_RESOLUTION_UNSPECIFIED (Varsayılan) 1120 70 560
MEDIA_RESOLUTION_LOW 280 70 280 + Doğal Metin
MEDIA_RESOLUTION_MEDIUM 560 70 560 + Doğal Metin
MEDIA_RESOLUTION_HIGH 1120 280 1.120 + Yerel Metin

Gemini 2.5 modelleri

MediaResolution Resim Video PDF (taranmış) PDF (Yerel)
MEDIA_RESOLUTION_UNSPECIFIED (Varsayılan) 256 + Pan & Scan (~2048) 256 256 + OCR 256 + Doğal Metin
MEDIA_RESOLUTION_LOW 64 64 64 + OCR 64 + Doğal Metin
MEDIA_RESOLUTION_MEDIUM 256 256 256 + OCR 256 + Doğal Metin
MEDIA_RESOLUTION_HIGH 256 + Pan & Scan 256 256 + OCR 256 + Doğal Metin

Doğru çözünürlüğü seçme

  • Varsayılan (UNSPECIFIED): Varsayılanla başlayın. En yaygın kullanım alanlarında kalite, gecikme ve maliyet arasında iyi bir denge sağlamak için ayarlanmıştır.
  • LOW: Maliyet ve gecikmenin en önemli olduğu, ayrıntılı bilgilerin daha az kritik olduğu senaryolarda kullanılır.
  • MEDIUM / HIGH: Görev, medyada karmaşık ayrıntıların anlaşılmasını gerektirdiğinde çözünürlüğü artırın. Bu özellik genellikle karmaşık görsel analiz, grafik okuma veya yoğun belge anlama için gereklidir.
  • Bölüm bazında kontrol (Gemini 3): Jeton kullanımını optimize etmek için bu özelliği kullanın. Örneğin, birden fazla resim içeren bir istemde karmaşık bir diyagram için HIGH, daha basit bağlamsal resimler için ise LOW veya MEDIUM kullanın.

Önerilen ayarlar

Aşağıda, desteklenen her medya türü için önerilen medya çözünürlüğü ayarları listelenmiştir.

Medya Türü Önerilen Ayar Maks. Jeton Sayısı (Max Tokens) Kullanım Yönergeleri
Resimler MEDIA_RESOLUTION_HIGH 1120 Maksimum kaliteyi sağlamak için çoğu görüntü analizi görevinde önerilir.
PDF'ler MEDIA_RESOLUTION_MEDIUM 560 Belge anlamak için idealdir. Kalite genellikle medium'da doygunluğa ulaşır. high'ya yükseltmek, standart dokümanlar için OCR sonuçlarını nadiren iyileştirir.
Video (Genel) MEDIA_RESOLUTION_LOW (veya MEDIA_RESOLUTION_MEDIUM) 70 (kare başına) Not: Video için low ve medium ayarları, bağlam kullanımını optimize etmek amacıyla aynı şekilde (70 jeton) değerlendirilir. Bu, çoğu eylem tanıma ve açıklama görevi için yeterlidir.
Video (Metin ağırlıklı) MEDIA_RESOLUTION_HIGH 280 (kare başına) Yalnızca kullanım alanında yoğun metin okuma (OCR) veya video karelerindeki küçük ayrıntılar yer aldığında gereklidir.

Kalite, gecikme ve maliyet arasında en iyi dengeyi bulmak için farklı çözünürlük ayarlarının uygulamanız üzerindeki etkisini her zaman test edin ve değerlendirin.

Sürüm uyumluluğu özeti

  • MediaResolution enum'u, medya girişini destekleyen tüm modellerde kullanılabilir.
  • Her enum düzeyiyle ilişkili jeton sayıları, Gemini 3 modelleri ile önceki Gemini sürümleri arasında farklıdır.
  • Part nesnelerinde media_resolution ayarı yalnızca Gemini 3 modellerinde kullanılabilir.

Sonraki adımlar