Medya çözünürlüğü

media_resolution parametresi, Gemini API'nin resim, video, ses ve PDF belgeleri gibi medya girişlerini nasıl işleyeceğini kontrol eder. Bu parametre, medya girişleri için ayrılan maksimum jeton sayısını belirleyerek yanıt kalitesi ile gecikme ve maliyet arasında denge kurmanıza olanak tanır. Görsel ve doküman girişlerinde jeton tahsisi çözünürlük ayarına göre ölçeklendirilirken ses girişleri tüm çözünürlük seviyelerinde saniyede sabit bir hızda jetonlaştırılır. 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:

• Parça başına (Gemini 4 ve Gemini 3 modelleri)

• generateContent isteğinin tamamı için genel olarak (tüm çok formatlı modeller)

Bölüm bazında medya çözünürlüğü (Gemini 4 ve Gemini 3)

Gemini 4 ve Gemini 3, isteğinizdeki her bir medya nesnesi için medya çözünürlüğünü ayarlamanıza olanak tanıyarak jeton kullanımını ayrıntılı bir şekilde optimize etmenizi sağlar. Tek bir istekte çözünürlük seviyelerini karıştırabilirsiniz. Örneğin, karmaşık bir diyagram için yüksek çözünürlük, bağlamsal bir resim için düşük çözünürlük kullanabilirsiniz. Bu ayar, belirli bir parça için genel yapılandırmayı geçersiz kılar. Varsayılan ayarlar için Token sayıları bölümüne bakın.

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

Global 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ı modeller tarafından 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.

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

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

Gemini API, medya çözünürlüğü için aşağıdaki seviyeleri 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 maliyetle sonuçlanır ancak daha az ayrıntı içerir.
• MEDIA_RESOLUTION_MEDIUM: Ayrıntı, maliyet ve gecikme arasında denge sağlar.
• MEDIA_RESOLUTION_HIGH: Daha yüksek birim sayısı, modelin çalışması için daha fazla ayrıntı sağlar ancak gecikme süresi ve maliyet artar.
• MEDIA_RESOLUTION_ULTRA_HIGH (Yalnızca parça başına): En yüksek jeton sayısı. Bilgisayar kullanımı gibi belirli kullanım alanları için gereklidir.

MEDIA_RESOLUTION_HIGH'nın çoğu kullanım alanı için optimum performans sağladığını unutmayın.

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

Jeton sayıları

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

Gemini 3 modelleri

Gemini 2.5 modelleri

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 çok önemli olduğu, ayrıntıların ise daha az kritik olduğu senaryolarda kullanın.
• 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 dokümanları anlama için gereklidir.
• ULTRA HIGH: Yalnızca parça başına ayarı için kullanılabilir. Bilgisayar kullanımı gibi belirli kullanım alanları için veya testlerde HIGH'e kıyasla belirgin bir iyileşme görüldüğünde önerilir.
• Bölüm bazında kontrol (Gemini 4 ve Gemini 3): Jeton kullanımını optimize eder. Örneğin, birden fazla resim içeren bir istemde karmaşık bir diyagram için HIGH, daha basit bağlamsal resimler için 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.

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.

Video işleme modlarıyla ilişki

media_resolution ve işleme parametreleri, video girişinin farklı yönlerini kontrol eder:

• media_resolution, her karenin çözünürlüğünü (kare başına jeton sayısı) kontrol eder.
• processing / media_processing kontrolleri, videodaki hangi içeriğin bağlama yükleneceğini belirler.

İkisini de aynı video girişinde ayarlayabilirsiniz. Örneğin, uzun bir videoda toplam jeton kullanımını en aza indirmek için düşük medya çözünürlüğüyle temsilci tabanlı işleme kullanabilirsiniz.

Video işleme modları hakkında ayrıntılı bilgi için Temsilci tabanlı video yorumlama kılavuzuna bakın.

Sürüm uyumluluğu özeti

• MediaResolution enum'u, medya girişi destekleyen tüm modellerde kullanılabilir.
• Her bir enum seviyesiyle ilişkili token sayıları, Gemini 4 / Gemini 3 modelleri ile önceki Gemini sürümleri arasında farklılık gösterir.
• Bağımsız Part nesnelerinde media_resolution ayarı Gemini 4 ve Gemini 3 modellerinde desteklenir.

Sonraki adımlar

• Gemini API'nin çok formatlı özellikleri hakkında daha fazla bilgiyi Resim Anlama, Video Anlama, Ses Anlama ve Doküman Anlama kılavuzlarında bulabilirsiniz.