הפרמטר 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 | תמונה | וידאו | אודיו | |
|---|---|---|---|---|
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.
השלבים הבאים
- מידע נוסף על היכולות המולטי-מודאליות של Gemini API זמין במדריכים בנושא הבנת תמונות, הבנת סרטונים, הבנת אודיו והבנת מסמכים.