הפרמטר media_resolution קובע איך Gemini API מעבד קלט מדיה כמו תמונות, סרטונים, אודיו ומסמכי PDF, על ידי הגדרת המספר המקסימלי של טוקנים שמוקצים לקלט מדיה. כך אתם יכולים לאזן בין איכות התגובה לבין זמן האחזור והעלות. בעוד שהקצאת הטוקנים של קלט חזותי וקלט של מסמכים משתנה בהתאם להגדרת הרזולוציה, קלט של אודיו עובר טוקניזציה בקצב קבוע לשנייה בכל רמות הרזולוציה. בקטע ספירת הטוקנים מפורטים ערכי ברירת המחדל של הגדרות שונות וההתאמה שלהם לטוקנים.
יש שתי דרכים להגדיר את רזולוציית המדיה:
לכל חלק (מודלים של Gemini 4 ו-Gemini 3)
באופן גלובלי לכל בקשת
generateContent(כל המודלים המולטי-מודאליים)
רזולוציית מדיה לכל חלק (Gemini 4 ו-Gemini 3)
Gemini 4 ו-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-4-argon'
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-4-argon';
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-4-argon"
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 4 ו-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 ו-processing שולטים בהיבטים שונים של קלט הווידאו:
media_resolutionשולט ברזולוציה של כל פריים (מספר הטוקנים לכל פריים).-
processing/media_processingקובעים איזה תוכן מהסרטון ייטען בהקשר.
אפשר להגדיר את שניהם באותו קלט וידאו. לדוגמה, אתם יכולים להשתמש בעיבוד מבוסס-סוכנים עם רזולוציית מדיה נמוכה כדי למזער את השימוש הכולל בטוקנים בסרטון ארוך.
פרטים על מצבי עיבוד וידאו זמינים במדריך הבנת וידאו באמצעות סוכנים.
סיכום תאימות הגרסאות
- הערך
MediaResolutionזמין לכל המודלים שתומכים בקלט מדיה. - כמות הטוקנים שמשויכת לכל רמת enum שונה בין מודלים של Gemini 4 או Gemini 3 לבין גרסאות קודמות של Gemini.
- אפשר להגדיר את
media_resolutionבאובייקטים בודדים שלPartבמודלים של Gemini 4 ו-Gemini 3.
השלבים הבאים
- מידע נוסף על היכולות המולטי-מודאליות של Gemini API זמין במדריכים בנושא הבנת תמונות, הבנת סרטונים, הבנת אודיו והבנת מסמכים.