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, ses ve PDF belgeleri gibi medya girişlerini nasıl işleyeceğini kontrol eder. Bu sayede, yanıt kalitesini gecikme ve maliyetle dengelemenize olanak tanır. Görsel ve belge girişleri, çözünürlük ayarına göre jeton dağıtımını ölçeklendirirken 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.

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

İç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 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 düşük çözünürlük kullanabilirsiniz.

from google import genai

client = genai.Client()

myfile = client.files.upload(file="path/to/image.jpg")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Describe this image:"},
        {
            "type": "image",
            "uri": myfile.uri,
            "mime_type": myfile.mime_type,
            "resolution": "high"
        }
    ]
)
print(interaction.output_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: { mime_type: "image/jpeg" },
  });

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "text", text: "Describe this image:" },
      {
        type: "image",
        uri: myfile.uri,
        mime_type: myfile.mimeType,
        resolution: "high"
      }
    ],
  });
  console.log(interaction.output_text);
}

await main();

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Describe the details in this high-resolution image.").build();
Content imageContent =
    ImageContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/image/scones.jpg")
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

# 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.8-flash",
    "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 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.
• medium: Ayrıntı, maliyet ve gecikme arasında 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, 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

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 öncelikli olduğu, ayrıntılı bilgilerin daha az önemli olduğu senaryolarda kullanılır.
• medium / high: Görev, medyada yer alan 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 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 agentic işlemeyi kullanabilirsiniz.

Video işleme modları hakkında ayrıntılı bilgi için Agentic video understanding (Agentic video anlama) kılavuzuna bakın.

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ı özellikleri hakkında daha fazla bilgiyi görüntü anlama, video anlama, ses anlama ve doküman anlama kılavuzlarında bulabilirsiniz.