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

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

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

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

השלבים הבאים