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 dengelemenizi sağlar. 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.

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

İçerik öğesi başına medya çözünürlüğü (Gemini 4 ve Gemini 3 modelleri)

Gemini 4 ve Gemini 3 modelleri, isteğinizdeki medya nesneleri için ayrı ayrı medya çözünürlüğü ayarlamanıza olanak tanıyarak jeton kullanımında ayrıntılı optimizasyon sağlar. Tek bir istekte çözünürlük seviyelerini 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.

Python

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)

JavaScript

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

Java

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

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/image.jpg", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Describe the details in this high-resolution image.",
                }),
                interactions.NewContent(interactions.ImageContent{
                    URI:        genai.Ptr(uploadedFile.URI),
                    MimeType:   interactions.ImageContentMimeType(uploadedFile.MIMEType).ToPointer(),
                    Resolution: interactions.MediaResolutionHigh.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

# 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 seviyeleri tanımlar:

  • unspecified: Varsayılan ayardır. Bu seviyenin jeton sayısı, Gemini 4/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şleme ve daha düşük maliyetle sonuçlanır ancak daha az ayrıntı içerir.
  • medium: Ayrıntı, maliyet ve gecikme arasında bir denge.
  • high: Daha yüksek birim sayısı, modelin çalışması için daha fazla ayrıntı sağlar ancak gecikme ve maliyet artar.
  • ultra_high (Yalnızca içerik öğesi başına): En yüksek jeton sayısı, bilgisayar kullanımı gibi belirli kullanım alanları için gereklidir.

high, çoğu kullanım alanında en iyi performansı sağlar.

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ısı

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

Gemini 4 ve Gemini 3 modelleri

MediaResolution Resim Video Ses PDF
unspecified (Varsayılan) 1120 70 25 (saniyede) 560
low 280 70 25 (saniye başına) 280 + Doğal Metin
medium 560 70 25 (saniye başına) 560 + Yerel Metin
high 1120 280 25 (saniye başına) 1120 + Native Text
ultra_high 2240 Yok Yok Yok

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ğlayacak şekilde 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 durum 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ı için veya testlerde high'e göre belirgin bir iyileşme görüldüğünde önerilir.
  • İçerik öğesi başına 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 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 Maksimum jeton sayısı Kullanım Yönergeleri
Resimler high 1120 Maksimum kaliteyi sağlamak için çoğu görüntü analizi görevinde önerilir.
PDF'ler medium 560 Doküman anlamak için idealdir. Kalite genellikle medium'da doygunluğa ulaşır. high'ya yükseltmek, standart belgeler için OCR sonuçlarını nadiren iyileştirir.
Video (Genel) low (veya 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ı) high 280 (kare başına) Yalnızca kullanım alanında yoğun metin (OCR) veya video karelerindeki küçük ayrıntılar okunuyorsa gereklidir.
Ses unspecified (Varsayılan) 25 (saniyede) Ses, desteklenen tüm çözünürlük ayarlarında (unspecified, low, medium ve high) saniyede 25 jetonluk sabit bir hızda parçalara ayrılır.

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, videodaki hangi içeriğin bağlama yükleneceğini kontrol eder.

Aynı video girişinde her ikisini de 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

  • Bağımsız içerik öğelerinde resolution ayarı Gemini 4 ve Gemini 3 modellerinde desteklenir.

Sonraki adımlar