רזולוציית המדיה

הפרמטר media_resolution קובע איך Gemini API מעבד קלט מדיה כמו תמונות, סרטונים, אודיו ומסמכי PDF, על ידי הגדרת המספר המקסימלי של טוקנים שמוקצים לקלט מדיה. כך אתם יכולים לאזן בין איכות התגובה לבין זמן האחזור והעלות. בעוד שהקצאת הטוקנים של קלט חזותי וקלט של מסמכים משתנה בהתאם להגדרת הרזולוציה, קלט של אודיו עובר טוקניזציה בקצב קבוע לשנייה בכל רמות הרזולוציה. בקטע ספירת הטוקנים מפורטים ערכי ברירת המחדל של הגדרות שונות וההתאמה שלהם לטוקנים.

יש שתי דרכים להגדיר את רזולוציית המדיה:

רזולוציית מדיה לכל חלק (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 תמונה סרטון אודיו PDF
‫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.

השלבים הבאים