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şlediğ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.
Medya çözünürlüğünü iki şekilde yapılandırabilirsiniz:
Parça başına (yalnızca Gemini 3)
generateContentisteğinin tamamı için küresel 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.
Python
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)
JavaScript
// 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();
REST
# 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.
Python
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)
JavaScript
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();
REST
# ... (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.- (Yakında kullanıma sunulacak)
MEDIA_RESOLUTION_ULTRA_HIGH: Bilgisayar kullanımı gibi belirli kullanım alanları için gereken en yüksek jeton sayısı.
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ğerine ve medya türüne göre yaklaşık jeton sayıları özetlenmektedir.
Gemini 3 Modelleri
| MediaResolution | Resim | Video | |
MEDIA_RESOLUTION_UNSPECIFIED (Varsayılan)
|
1120 | 70 | 560 |
MEDIA_RESOLUTION_LOW
|
280 | 70 | 280 + Doğal Metin |
MEDIA_RESOLUTION_MEDIUM
|
560 | 70 | 560 + Doğal Metin |
MEDIA_RESOLUTION_HIGH
|
1120 | 280 | 1.120 + Yerel Metin |
Gemini 2.5 modelleri
| MediaResolution | Resim | Video | PDF (taranmış) | PDF (Yerel) |
MEDIA_RESOLUTION_UNSPECIFIED (Varsayılan)
|
256 + Pan & Scan (~2048) | 256 | 256 + OCR | 256 + Doğal Metin |
MEDIA_RESOLUTION_LOW
|
64 | 64 | 64 + OCR | 64 + Doğal Metin |
MEDIA_RESOLUTION_MEDIUM
|
256 | 256 | 256 + OCR | 256 + Doğal Metin |
MEDIA_RESOLUTION_HIGH
|
256 + Pan & Scan | 256 | 256 + OCR | 256 + Doğal Metin |
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.- Bölüm bazında kontrol (Gemini 3): Jeton kullanımını optimize etmek için bu özelliği kullanın. Ö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 | Maks. Jeton Sayısı (Max Tokens) | Kullanım Yönergeleri |
| Resimler | MEDIA_RESOLUTION_HIGH
|
1120 | Maksimum kaliteyi sağlamak için çoğu görüntü analizi görevinde önerilir. |
| PDF'ler | MEDIA_RESOLUTION_MEDIUM
|
560 | Belge anlamak için idealdir. Kalite genellikle medium'da doygunluğa ulaşır. high'ya yükseltmek, standart dokümanlar için OCR sonuçlarını nadiren iyileştirir.
|
| Video (Genel) | MEDIA_RESOLUTION_LOW (veya MEDIA_RESOLUTION_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ı) | MEDIA_RESOLUTION_HIGH
|
280 (kare başına) | Yalnızca kullanım alanında yoğun metin okuma (OCR) veya video karelerindeki küçük ayrıntılar yer aldığında gereklidir. |
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
MediaResolutionenum'u, medya girişini 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ıdır.
Partnesnelerindemedia_resolutionayarı 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 ve Doküman anlama kılavuzlarında bulabilirsiniz.