تتحكّم المَعلمة 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();
جافا
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 + نص أصلي |
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 إلى تحسين نتائج التعرّف البصري على الأحرف للمستندات العادية إلا نادرًا. |
| الفيديو (عام) | low (أو medium) |
70 (لكل إطار) | ملاحظة: بالنسبة إلى الفيديو، يتم التعامل مع إعدادات low وmedium بشكل مماثل (70 رمزًا مميزًا) لتحسين استخدام السياق. وهذا كافٍ لمعظم مهام التعرّف على الإجراءات ووصفها. |
| فيديو (يتضمّن الكثير من النصوص) | high |
280 (لكل إطار) | مطلوب فقط عندما تتضمن حالة الاستخدام قراءة نص كثيف (التعرّف البصري على الأحرف) أو تفاصيل صغيرة داخل إطارات الفيديو. |
| الصوت | unspecified (تلقائي) |
25 (في الثانية) | يتم تقسيم الصوت إلى رموز بمعدّل ثابت يبلغ 25 رمزًا في الثانية على مستوى جميع إعدادات الدقة المتوافقة (unspecified وlow وmedium وhigh). |
اختبِر دائمًا تأثير إعدادات الدقة المختلفة على تطبيقك وقيِّمها للعثور على أفضل توازن بين الجودة ووقت الاستجابة والتكلفة.
العلاقة مع أوضاع معالجة الفيديو
تتحكّم مَعلمة media_resolution ومَعلمات المعالجة في جوانب مختلفة من إدخال الفيديو:
- يتحكّم
media_resolutionفي دقة كل إطار (عدد الرموز المميزة لكل إطار). - يتحكّم
processing/media_processingبالمحتوى الذي يتم تحميله من الفيديو إلى السياق.
ويمكنك ضبط كليهما على مصدر إدخال الفيديو نفسه. على سبيل المثال، يمكنك استخدام المعالجة المستندة إلى الوكلاء مع دقة وسائط منخفضة لتقليل إجمالي استخدام الرموز المميّزة لفيديو طويل.
للحصول على تفاصيل حول أوضاع معالجة الفيديو، يُرجى الاطّلاع على دليل فهم الفيديو المستند إلى الذكاء الاصطناعي.
ملخّص التوافق مع الإصدارات
- يمكن ضبط
resolutionعلى عناصر محتوى فردية في نموذجَي Gemini 4 وGemini 3.
الخطوات التالية
- يمكنك الاطّلاع على مزيد من المعلومات حول الإمكانات المتعدّدة الوسائط في Gemini API في أدلة فهم الصور وفهم الفيديوهات وفهم الصوت وفهم المستندات.