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

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

אתם יכולים להגדיר את רזולוציית המדיה לאובייקטים נפרדים של מדיה (פריטי תוכן) בבקשה (מודלים Gemini 4 ו-Gemini 3).

עיבוד מדיה לכל פריט תוכן (מודלים של Gemini 4 ו-Gemini 3)

במודלים של Gemini 4 ו-Gemini 3 אפשר להגדיר רזולוציה לאובייקטים ספציפיים של מדיה בבקשה, וכך לבצע אופטימיזציה מדויקת של השימוש בטוקנים. אפשר לשלב רמות רזולוציה שונות בבקשה אחת. לדוגמה, להשתמש ברזולוציה גבוהה לתרשים מורכב וברזולוציה נמוכה לתמונה פשוטה שמוסיפה הקשר.

Python

from google import genai

client = genai.Client()

myfile = client.files.upload(file="path/to/image.jpg")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Describe this image:"},
        {
            "type": "image",
            "uri": myfile.uri,
            "mime_type": myfile.mime_type,
            "resolution": "high"
        }
    ]
)
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/image.jpg",
    config: { mime_type: "image/jpeg" },
  });

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "text", text: "Describe this image:" },
      {
        type: "image",
        uri: myfile.uri,
        mime_type: myfile.mimeType,
        resolution: "high"
      }
    ],
  });
  console.log(interaction.output_text);
}

await main();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Describe the details in this high-resolution image.").build();
Content imageContent =
    ImageContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/image/scones.jpg")
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/image.jpg", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Describe the details in this high-resolution image.",
                }),
                interactions.NewContent(interactions.ImageContent{
                    URI:        genai.Ptr(uploadedFile.URI),
                    MimeType:   interactions.ImageContentMimeType(uploadedFile.MIMEType).ToPointer(),
                    Resolution: interactions.MediaResolutionHigh.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

# First upload the file using the Files API, then use the URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Describe this image:"},
      {
        "type": "image",
        "uri": "YOUR_FILE_URI",
        "mime_type": "image/jpeg",
        "resolution": "high"
      }
    ]
  }'

ערכי הרזולוציה הזמינים

‫Gemini API מגדיר את הרמות הבאות לרזולוציית מדיה:

  • ‫unspecified: הגדרת ברירת המחדל. כמות הטוקנים ברמה הזו משתנה באופן משמעותי בין מודל Gemini 4/3 לבין מודלים קודמים של Gemini.
  • ‫low: כמות טוקנים קטנה יותר, שמובילה לעיבוד מהיר יותר ולעלות נמוכה יותר, אבל עם פחות פרטים.
  • ‫medium: איזון בין רמת הפירוט, העלות וזמן האחזור.
  • ‫high: כמות טוקנים גדולה יותר, שמספקת למודל יותר פרטים לעבוד איתם, אבל מגדילה את זמן האחזור והעלות.
  • ‫ultra_high (לכל פריט תוכן בלבד): מספר הטוקנים הגבוה ביותר, נדרש לתרחישי שימוש ספציפיים כמו שימוש במחשב.

חשוב לזכור שהמערך high מספק את הביצועים האופטימליים ברוב תרחישי השימוש.

המספר המדויק של הטוקנים שנוצרים בכל אחת מהרמות האלה תלוי בסוג המדיה (תמונה, סרטון, אודיו, PDF) ובגרסת המודל.

כמות הטוקנים

בטבלאות הבאות מופיע סיכום של מספר האסימונים המשוער לכל ערך media_resolution ולכל סוג מדיה לכל משפחת מודלים.

המודלים Gemini 4 ו-Gemini 3

MediaResolution תמונה וידאו אודיו PDF
‫unspecified (ברירת מחדל) 1120 70 ‫25 (לשנייה) 560
low 280 70 ‫25 (לשנייה) ‫280 + טקסט חי
medium 560 70 ‫25 (לשנייה) ‫560 + Native Text
high 1120 280 ‫25 (לשנייה) ‫1120 + טקסט חי
ultra_high 2240 לא רלוונטי לא רלוונטי לא רלוונטי

איך בוחרים את הרזולוציה המתאימה

  • ברירת מחדל (unspecified): מתחילים עם ברירת המחדל. הוא מותאם לאיזון טוב בין איכות, זמן אחזור ועלות ברוב תרחישי השימוש הנפוצים.
  • ‫low: מתאים לתרחישים שבהם העלות והחביון הם בעלי חשיבות עליונה, ופרטים מדויקים פחות קריטיים.
  • ‫medium / high: כדאי להגדיל את הרזולוציה כשהמשימה דורשת הבנה של פרטים מורכבים במדיה. זה נדרש לעיתים קרובות לניתוח חזותי מורכב, לקריאת תרשימים או להבנת מסמכים עמוסים.
  • ultra_high – זמין רק להגדרה של כל פריט תוכן. מומלץ לתרחישי שימוש ספציפיים, כמו שימוש במחשב, או במקרים שבהם בדיקות מראות שיפור ברור לעומת high.
  • שליטה בכל פריט תוכן (Gemini 4 ו-Gemini 3): אופטימיזציה של השימוש בטוקנים. לדוגמה, בהנחיה עם כמה תמונות, אפשר להשתמש ב-high לדיאגרמה מורכבת וב-low או ב-medium לתמונות פשוטות יותר שנותנות הקשר.

הגדרות מומלצות

ברשימה הבאה מפורטות הגדרות הרזולוציה המומלצות לכל סוג מדיה נתמך.

סוג מדיה הגדרה מומלצת מספר הטוקנים המקסימלי הנחיות לשימוש
תמונות high 1120 מומלץ לרוב משימות ניתוח התמונות כדי להבטיח איכות מקסימלית.
קובצי PDF medium 560 אופטימלי להבנת מסמכים. האיכות בדרך כלל מגיעה לרוויה ב-medium. הגדלה ל-high משפרת לעיתים רחוקות את תוצאות ה-OCR במסמכים רגילים.
סרטון (כללי) low (או medium) ‫70 (לכל פריים) הערה: בסרטונים, ההגדרות של low ו-medium מטופלות באופן זהה (70 טוקנים) כדי לייעל את השימוש בהקשר. זה מספיק לרוב המשימות של זיהוי פעולות ותיאור.
סרטון (הרבה טקסט) high ‫280 (לכל פריים) נדרש רק כשבתרחיש השימוש צריך לקרוא טקסט צפוף (OCR) או פרטים קטנים בפריימים של סרטונים.
אודיו ‫unspecified (ברירת מחדל) ‫25 (לשנייה) האודיו עובר טוקניזציה בקצב קבוע של 25 טוקנים לשנייה בכל הגדרות הרזולוציה הנתמכות (unspecified, ‏low, ‏medium ו-high).

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

הקשר למצבי עיבוד הסרטונים

הפרמטרים media_resolution ו-processing שולטים בהיבטים שונים של קלט הווידאו:

  • הפרמטר media_resolution שולט ברזולוציה של כל פריים (מספר הטוקנים לכל פריים).
  • ‫processing / media_processing קובע איזה תוכן מהסרטון נטען להקשר.

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

פרטים על מצבי עיבוד של סרטונים זמינים במדריך הבנת סרטונים באמצעות סוכנים.

סיכום תאימות הגרסאות

  • הגדרת resolution בפריטי תוכן ספציפיים נתמכת במודלים Gemini 4 ו-Gemini 3.

השלבים הבאים