הפרמטר media_resolution קובע איך Gemini API מעבד קלט של מדיה כמו תמונות, סרטונים ומסמכי PDF. הוא מגדיר את מספר הטוקנים המקסימלי שמוקצה לקלט של מדיה, וכך מאפשר לכם לאזן בין איכות התשובה לבין זמן האחזור והעלות. בקטע ספירת טוקנים מפורטים ערכי ברירת המחדל של הגדרות שונות וההתאמה שלהם לטוקנים.
יש שתי דרכים להגדיר את רזולוציית המדיה:
לכל חלק (רק Gemini 3)
באופן גלובלי לכל
generateContentבקשה (כל המודלים מרובי-האופנים)
רזולוציית מדיה לכל חלק (Gemini 3 בלבד)
Gemini 3 מאפשר לכם להגדיר רזולוציית מדיה לאובייקטים ספציפיים של מדיה בבקשה, וכך לבצע אופטימיזציה פרטנית של השימוש בטוקנים. אפשר לשלב רמות רזולוציה שונות בבקשה אחת. לדוגמה, שימוש ברזולוציה גבוהה לתרשים מורכב וברזולוציה נמוכה לתמונה פשוטה שמוסיפה הקשר. ההגדרה הזו מחליפה כל הגדרה גלובלית של חלק ספציפי. הגדרות ברירת המחדל מפורטות בקטע ספירת טוקנים.
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
רזולוציית מדיה גלובלית
אפשר להגדיר רזולוציית ברירת מחדל לכל חלקי המדיה בבקשה באמצעות התג GenerationConfig. כל המודלים הרב-אופניים תומכים בזה. אם בקשה כוללת גם הגדרות גלובליות וגם הגדרות לכל חלק, ההגדרה לכל חלק מקבלת עדיפות עבור הפריט הספציפי הזה.
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"
}
}'
ערכי הרזולוציה הזמינים
ב-Gemini API מוגדרות הרמות הבאות של רזולוציית מדיה:
-
MEDIA_RESOLUTION_UNSPECIFIED: הגדרת ברירת המחדל. מספר הטוקנים ברמה הזו משתנה באופן משמעותי בין Gemini 3 לבין מודלים קודמים של Gemini. -
MEDIA_RESOLUTION_LOW: מספר הטוקנים נמוך יותר, ולכן העיבוד מהיר יותר והעלות נמוכה יותר, אבל יש פחות פרטים. -
MEDIA_RESOLUTION_MEDIUM: איזון בין רמת הפירוט, העלות וההשהיה. -
MEDIA_RESOLUTION_HIGH: מספר גבוה יותר של טוקנים, שמספק יותר פרטים למודל לעבודה, אבל על חשבון עלייה בחביון ובעלות. - (בקרוב)
MEDIA_RESOLUTION_ULTRA_HIGH: מספר האסימונים הכי גבוה שנדרש לתרחישי שימוש ספציפיים, כמו שימוש במחשב.
המספר המדויק של הטוקנים שנוצרים בכל אחת מהרמות האלה תלוי בסוג המדיה (תמונה, סרטון, PDF) ובגרסת המודל.
מספר הטוקנים
בטבלאות הבאות מפורטים מספר האסימונים המשוער לכל ערך media_resolution ולכל סוג מדיה, לפי משפחת מודלים.
מודלים של Gemini 3
| MediaResolution | תמונה | סרטון | |
MEDIA_RESOLUTION_UNSPECIFIED (ברירת מחדל)
|
1120 | 70 | 560 |
MEDIA_RESOLUTION_LOW
|
280 | 70 | 280 + טקסט מותאם |
MEDIA_RESOLUTION_MEDIUM
|
560 | 70 | 560 + טקסט מותאם |
MEDIA_RESOLUTION_HIGH
|
1120 | 280 | 1120 + טקסט מותאם |
מודלים של Gemini 2.5
| MediaResolution | תמונה | סרטון | PDF (נסרק) | PDF (Native) |
MEDIA_RESOLUTION_UNSPECIFIED (ברירת מחדל)
|
256 + Pan & Scan (~2048) | 256 | 256 + OCR | 256 + טקסט מותאם |
MEDIA_RESOLUTION_LOW
|
64 | 64 | 64 + OCR | 64 + טקסט מותאם |
MEDIA_RESOLUTION_MEDIUM
|
256 | 256 | 256 + OCR | 256 + טקסט מותאם |
MEDIA_RESOLUTION_HIGH
|
256 + Pan & Scan | 256 | 256 + OCR | 256 + טקסט מותאם |
בחירת הרזולוציה המתאימה
- ברירת מחדל (
UNSPECIFIED): מתחילים עם ברירת המחדל. הוא מותאם לאיזון טוב בין איכות, זמן אחזור ועלות ברוב התרחישים הנפוצים. -
LOW: מתאים לתרחישים שבהם העלות והחביון הם בעלי חשיבות עליונה, ופרטים מדויקים פחות קריטיים. -
MEDIUM/HIGH: הגדלת הרזולוציה כשנדרשת הבנה של פרטים מורכבים במדיה. היכולת הזו נדרשת לרוב לניתוח חזותי מורכב, לקריאת תרשימים או להבנת מסמכים עמוסים במידע. - שליטה בכל חלק (Gemini 3): אפשר להשתמש באפשרות הזו כדי לייעל את השימוש בטוקנים. לדוגמה, בהנחיה עם כמה תמונות, אפשר להשתמש ב-
HIGHלתרשים מורכב וב-LOWאו ב-MEDIUMלתמונות פשוטות יותר שנותנות הקשר.
הגדרות מומלצות
ברשימה הבאה מפורטות הגדרות הרזולוציה המומלצות לכל סוג מדיה נתמך.
| סוג המדיה | הגדרה מומלצת | מספר הטוקנים המקסימלי | הנחיות לשימוש |
| תמונות | MEDIA_RESOLUTION_HIGH
|
1120 | מומלץ לרוב משימות ניתוח התמונות כדי להבטיח איכות מקסימלית. |
| קובצי PDF | MEDIA_RESOLUTION_MEDIUM
|
560 | אופטימלי להבנת מסמכים; האיכות מגיעה בדרך כלל לנקודת רוויה ב-medium. הגדלה ל-high משפרת לעיתים רחוקות את תוצאות ה-OCR במסמכים רגילים.
|
| סרטון (כללי) | MEDIA_RESOLUTION_LOW (או MEDIA_RESOLUTION_MEDIUM)
|
70 (לכל פריים) | הערה: כשמדובר בסרטונים, ההגדרות low ו-medium מטופלות באופן זהה (70 טוקנים) כדי למקסם את השימוש בהקשר. זה מספיק לרוב המשימות של זיהוי פעולות ותיאור שלהן.
|
| סרטון (עם הרבה טקסט) | MEDIA_RESOLUTION_HIGH
|
280 (לכל פריים) | נדרש רק אם תרחיש השימוש כולל קריאת טקסט צפוף (OCR) או פרטים קטנים בתוך פריים של סרטון. |
חשוב תמיד לבדוק ולהעריך את ההשפעה של הגדרות רזולוציה שונות על האפליקציה הספציפית שלכם, כדי למצוא את האיזון הטוב ביותר בין איכות, זמן אחזור ועלות.
סיכום תאימות הגרסה
- ה-enum
MediaResolutionזמין לכל המודלים שתומכים בהזנת מדיה. - מספר הטוקנים שמשויך לכל רמת enum שונה בין מודלים של Gemini 3 לבין גרסאות קודמות של Gemini.
- הגדרת
media_resolutionעל אובייקטיםPartספציפיים בלעדית למודלים של Gemini 3.
השלבים הבאים
- במדריכים בנושא הבנת תמונות, הבנת סרטונים והבנת מסמכים אפשר לקרוא מידע נוסף על היכולות המולטימודאליות של Gemini API.