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şleyeceğini kontrol eder. Bu sayede, yanıt kalitesi ile gecikme ve maliyet arasında denge kurabilirsiniz. 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 (yalnızca Gemini 3)

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

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.

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)

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

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

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)

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();

# ... (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.
• MEDIA_RESOLUTION_ULTRA_HIGH (Yalnızca bölüm 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 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ğeri ve medya türü başına 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 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.
• ULTRA HIGH: Yalnızca parça başına ayar için kullanılabilir. Bilgisayar kullanımı gibi belirli kullanım alanları veya testlerin HIGH üzerinde net bir iyileşme gösterdiği durumlarda önerilir.
• Bölüm bazında kontrol (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 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.

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şi 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ılık gösterir.
• Part nesnelerde media_resolution ayarı yalnızca Gemini 3 modellerinde kullanılabilir.

Sonraki adımlar

• Gemini API'nin çok formatlı özellikleriyle ilgili daha fazla bilgiyi Resim anlama, Video anlama ve Doküman anlama kılavuzlarında bulabilirsiniz.