הפרמטר 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 available in the v1beta API version.
client = genai.Client(
http_options={
'api_version': 'v1beta',
}
)
# 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.1-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: 'v1beta' } });
// 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.1-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.1-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/v1beta/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-3.8-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-3.8-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-3.8-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(לכל חלק בלבד): כמות הטוקנים הגבוהה ביותר, נדרש לתרחישי שימוש ספציפיים כמו שימוש במחשב.
שימו לב שהערך MEDIA_RESOLUTION_HIGH מספק את הביצועים האופטימליים ברוב תרחישי השימוש.
המספר המדויק של הטוקנים שנוצרים בכל אחת מהרמות האלה תלוי בסוג המדיה (תמונה, סרטון, אודיו, PDF) ובגרסת המודל.
מספר הטוקנים
בטבלאות הבאות מפורטות כמויות הטוקנים המשוערות לכל ערך media_resolution ולכל סוג מדיה, לפי משפחת מודלים.
מודלים של Gemini 3
| MediaResolution | תמונה | סרטון | אודיו | |
MEDIA_RESOLUTION_UNSPECIFIED (ברירת מחדל)
|
1120 | 70 | 25 (לשנייה) | 560 |
MEDIA_RESOLUTION_LOW
|
280 | 70 | 25 (לשנייה) | 280 + טקסט חי |
MEDIA_RESOLUTION_MEDIUM
|
560 | 70 | 25 (לשנייה) | 560 + טקסט חי |
MEDIA_RESOLUTION_HIGH
|
1120 | 280 | 25 (לשנייה) | 1120 + טקסט חי |
MEDIA_RESOLUTION_ULTRA_HIGH
|
2240 | לא רלוונטי | לא רלוונטי | לא רלוונטי |
מודלים של Gemini 2.5
| MediaResolution | תמונה | סרטון | אודיו | PDF (נסרק) | PDF (Native) |
MEDIA_RESOLUTION_UNSPECIFIED (ברירת מחדל)
|
256 + Pan & Scan (~2048) | 256 | 32 (לשנייה) | 256 + OCR | 256 + טקסט חי |
MEDIA_RESOLUTION_LOW
|
64 | 64 | 32 (לשנייה) | 64 + OCR | 64 + טקסט חי |
MEDIA_RESOLUTION_MEDIUM
|
256 | 256 | 32 (לשנייה) | 256 + OCR | 256 + טקסט חי |
MEDIA_RESOLUTION_HIGH
|
256 + Pan & Scan | 256 | 32 (לשנייה) | 256 + OCR | 256 + טקסט חי |
בחירת הרזולוציה המתאימה
- ברירת מחדל (
UNSPECIFIED): מתחילים עם ברירת המחדל. הוא מותאם לאיזון טוב בין איכות, זמן אחזור ועלות ברוב התרחישים הנפוצים. -
LOW: מתאים לתרחישים שבהם העלות והחביון הם בעלי חשיבות עליונה, ופרטים מדויקים פחות קריטיים. -
MEDIUM/HIGH: הגדלת הרזולוציה כשנדרשת הבנה של פרטים מורכבים במדיה. השימוש בתכונה הזו נדרש בדרך כלל לניתוח חזותי מורכב, לקריאת תרשימים או להבנת מסמכים עמוסים במידע. -
ULTRA HIGH– זמין רק להגדרה לכל חלק. מומלץ לתרחישי שימוש ספציפיים, כמו שימוש במחשב או במקרים שבהם בדיקות מראות שיפור ברור לעומת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) או פרטים קטנים בתוך פריים של סרטון. |
| אודיו | MEDIA_RESOLUTION_UNSPECIFIED (ברירת מחדל)
|
25 (לשנייה) ל-Gemini 3; 32 (לשנייה) ל-Gemini 2.5 | האודיו עובר טוקניזציה בקצב קבוע לשנייה בכל הגדרות הרזולוציה הנתמכות (unspecified, low, medium ו-high).
|
חשוב תמיד לבדוק ולהעריך את ההשפעה של הגדרות רזולוציה שונות על האפליקציה הספציפית שלכם, כדי למצוא את האיזון הטוב ביותר בין איכות, זמן אחזור ועלות.
הקשר בין מצבי העיבוד של הסרטון
הפרמטרים של media_resolution ושל העיבוד שולטים בהיבטים שונים של קלט הווידאו:
-
media_resolutionשולט ברזולוציה של כל פריים (מספר הטוקנים לכל פריים). -
processing/media_processingקובעים איזה תוכן מהסרטון ייטען בהקשר.
אפשר להגדיר את שניהם באותו קלט וידאו. לדוגמה, אפשר להשתמש בעיבוד מבוסס-סוכן עם רזולוציית מדיה נמוכה כדי למזער את השימוש הכולל בטוקנים בסרטון ארוך.
פרטים על מצבי עיבוד של סרטונים זמינים במדריך הבנת סרטונים באמצעות AI.
סיכום תאימות הגרסה
- ה-enum
MediaResolutionזמין לכל המודלים שתומכים בקלט מדיה. - מספר הטוקנים שמשויך לכל רמת enum שונה בין מודלים של Gemini 3 לבין גרסאות קודמות של Gemini.
- ההגדרה
media_resolutionעל אובייקטיםPartספציפיים בלעדית למודלים של Gemini 3.
השלבים הבאים
- במדריכים הבנת תמונות, הבנת סרטונים, הבנת אודיו והבנת מסמכים אפשר לקרוא מידע נוסף על היכולות המולטי-מודאליות של Gemini API.