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

İsteğinizdeki bağımsız medya nesneleri (içerik öğeleri) için medya çözünürlüğünü yapılandırabilirsiniz (yalnızca Gemini 3).

İçerik öğesi 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 parça 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.

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

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

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

• 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.
• low: Daha az ayrıntı içeren ancak daha hızlı işleme ve daha düşük maliyet sağlayan daha düşük jeton sayısı.
• medium: Ayrıntı, maliyet ve gecikme arasında bir denge.
• high: Daha yüksek jeton sayısı, gecikme ve maliyet artışı karşılığında modelin çalışması için daha fazla ayrıntı sağlar.
• ultra_high (Yalnızca içerik öğesi başına): En yüksek jeton sayısıdır. Bilgisayar kullanımı gibi belirli kullanım alanları için gereklidir.

high seçeneğinin çoğu kullanım alanında 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 her media_resolution değeri ve medya türüne ait yaklaşık jeton sayıları özetlenmektedir.

Gemini 3 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 ise 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 içerik öğesi 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.
• İçerik öğesi başına 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

• resolution ayarını tek tek içerik öğelerinde belirleme yalnızca Gemini 3 modellerinde kullanılabilir.

Sonraki adımlar

• Gemini API'nin çok formatlı özellikleriyle ilgili daha fazla bilgiyi görüntü anlama, video anlama ve doküman anlama kılavuzlarında bulabilirsiniz.