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 | |
|---|---|---|---|---|
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 testlerdehigh'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 iselowveyamediumkullanı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
resolutionayarı Gemini 4 ve Gemini 3 modellerinde desteklenir.
Sonraki adımlar
- Gemini API'nin çok formatlı özellikleri hakkında daha fazla bilgiyi görüntü anlama, video anlama, ses anlama ve belge anlama kılavuzlarında bulabilirsiniz.