درجة دقة الوسائط

يتحكّم المَعلمة media_resolution في طريقة معالجة Gemini API لمدخلات الوسائط، مثل الصور والفيديوهات والصوت ومستندات PDF، من خلال تحديد الحد الأقصى لعدد الرموز المميزة المخصّصة لمدخلات الوسائط، ما يتيح لك تحقيق التوازن بين جودة الردود ووقت الاستجابة والتكلفة. في حين أنّ المدخلات المرئية ومدخلات المستندات تحدّد عدد الرموز المميزة المخصّصة استنادًا إلى إعداد درجة الدقة، يتم تحويل المدخلات الصوتية إلى رموز مميزة بمعدّل ثابت في الثانية على جميع مستويات الدقة. للاطّلاع على الإعدادات المختلفة والقيم التلقائية وكيفية توافقها مع الرموز المميّزة، يُرجى الانتقال إلى قسم عدد الرموز المميّزة.

يمكنك ضبط دقة الوسائط لكل عنصر وسائط (عنصر محتوى) على حدة ضمن طلبك (Gemini 3 فقط).

دقة الوسائط لكل عنصر محتوى (Gemini 3 فقط)

يتيح لك Gemini 3 ضبط دقة الوسائط لكائنات الوسائط الفردية ضمن طلبك، ما يوفّر تحسينًا دقيقًا لاستخدام الرموز المميزة. يمكنك الجمع بين مستويات الدقة في طلب واحد. على سبيل المثال، استخدام دقة عالية لمخطط بياني معقّد ودقة منخفضة لصورة بسيطة ذات صلة بالموضوع

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)

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(""));

# 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 3 ونماذج Gemini السابقة.
• low: عدد أقل من الرموز المميزة، ما يؤدي إلى معالجة أسرع وتكلفة أقل، ولكن مع تفاصيل أقل
• ‫medium: تحقيق التوازن بين التفاصيل والتكلفة ووقت الاستجابة
• ‫high: عدد الرموز المميزة أكبر، ما يوفّر تفاصيل أكثر ليعمل النموذج عليها، ولكن على حساب زيادة وقت الاستجابة والتكلفة.
• ultra_high (لكل عنصر محتوى فقط): أعلى عدد من الرموز المميزة، وهو مطلوب لحالات استخدام معيّنة مثل استخدام الكمبيوتر.

يُرجى العِلم أنّ high يوفّر الأداء الأمثل لمعظم حالات الاستخدام.

يعتمد العدد الدقيق للرموز المميزة التي يتم إنشاؤها لكل مستوى من هذه المستويات على نوع الوسائط (صورة أو فيديو أو صوت أو ملف PDF) وإصدار النموذج.

عدد الرموز المميّزة

تلخّص الجداول أدناه عدد الرموز التقريبي لكل قيمة media_resolution ونوع وسائط لكل مجموعة نماذج.

نماذج Gemini 3

اختيار درجة الدقة المناسبة

• تلقائي (unspecified): ابدأ بالخيار التلقائي. تم ضبطه لتحقيق توازن جيد بين الجودة والوقت المستغرق والتكلفة في معظم حالات الاستخدام الشائعة.
• low: استخدِم هذا الخيار في الحالات التي تكون فيها التكلفة ووقت الاستجابة في غاية الأهمية، وتكون التفاصيل الدقيقة أقل أهمية.
• medium / high: زيادة درجة الدقة عندما تتطلّب المهمة فهم تفاصيل معقّدة في الوسائط وغالبًا ما يكون ذلك ضروريًا لإجراء تحليل مرئي معقّد أو قراءة الرسوم البيانية أو فهم المستندات الكثيفة.
• ultra_high: يتوفّر هذا الخيار فقط لإعدادات كل عنصر من عناصر المحتوى. يُنصح باستخدامها في حالات استخدام معيّنة، مثل استخدام الكمبيوتر أو عندما تُظهر الاختبارات تحسّنًا واضحًا مقارنةً بـ high.
• التحكّم في كل عنصر من عناصر المحتوى (Gemini 3): يحسِّن استخدام الرموز المميزة. على سبيل المثال، في طلب يتضمّن صورًا متعددة، استخدِم high لرسم تخطيطي معقّد وlow أو medium لصور سياقية أبسط.

الإعدادات المقترَحة

في ما يلي قائمة بإعدادات دقة الوسائط المقترَحة لكل نوع من أنواع الوسائط المتوافقة.

ننصحك دائمًا باختبار وتقييم تأثير إعدادات الدقة المختلفة على تطبيقك للعثور على أفضل حلّ وسط بين الجودة والوقت المستغرق والتكلفة.

العلاقة بأوضاع معالجة الفيديو

تتحكّم المَعلمتَين media_resolution والمعالجة في جوانب مختلفة من إدخال الفيديو:

• يتحكّم media_resolution في دقة كل إطار (عدد الرموز المميزة لكل إطار).
• تتحكّم processing / media_processing في المحتوى الذي يتم تحميله من الفيديو إلى السياق.

يمكنك ضبط كليهما على إدخال الفيديو نفسه. على سبيل المثال، يمكنك استخدام المعالجة المستندة إلى الوكيل مع درجة دقة منخفضة للوسائط لتقليل إجمالي استخدام الرموز المميزة لفيديو طويل.

للحصول على تفاصيل حول أوضاع معالجة الفيديو، يُرجى الاطّلاع على دليل فهم الفيديو المستند إلى الذكاء الاصطناعي.

ملخّص التوافق مع الإصدارات

• إنّ ضبط resolution على عناصر المحتوى الفردية متاح حصريًا في نماذج Gemini 3.

الخطوات التالية

• يمكنك الاطّلاع على مزيد من المعلومات حول إمكانات Gemini API المتعددة الوسائط في أدلة فهم الصور وفهم الفيديوهات وفهم الصوت وفهم المستندات.