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

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

يمكنك ضبط دقة الوسائط بطريقتَين:

• لكل جزء (نموذجا Gemini 4 وGemini 3)

• على مستوى العالم لطلب generateContent كامل (جميع النماذج المتعدّدة الوسائط)

دقة الوسائط لكل جزء (Gemini 4 وGemini 3)

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

from google import genai
from google.genai import types

# The media_resolution parameter for parts is available in the v1beta API version.
client = genai.Client(
  http_options={
      'api_version': 'v1beta',
  }
)

# 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-4-argon'

response = client.models.generate_content(
    model=model_name,
    contents=["Describe these images:", image_part_high]
)
print(response.text)

// 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: 'v1beta' } });

// 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-4-argon';
    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();

# 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-4-argon"

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/v1beta/models/${MODEL_ID}:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

دقة الوسائط العالمية

يمكنك ضبط دقة تلقائية لجميع أجزاء الوسائط في الطلب باستخدام GenerationConfig. تتوفّر هذه الميزة في جميع النماذج المتعدّدة الوسائط. إذا كان الطلب يتضمّن كلاً من الإعدادات العامة والإعدادات الخاصة بكل جزء، تكون الأولوية للإعدادات الخاصة بكل جزء في ما يتعلّق بهذا العنصر المحدّد.

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-3.8-flash',
    contents=["Describe this image:", image_part],
    config=config
)
print(response.text)

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-3.8-flash',
      contents: ["Describe this image:", imagePart],
      config: {
         mediaResolution: MediaResolution.MEDIA_RESOLUTION_HIGH
      }
   });
   console.log(response.text);
}
run();

# ... (Base64 encoding logic) ...

curl -s -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-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 (لكل جزء فقط): أعلى عدد من الرموز المميّزة، وهو مطلوب لحالات استخدام معيّنة، مثل استخدام الكمبيوتر.

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

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

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

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

نماذج Gemini 3

نماذج Gemini 2.5

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

• الإعداد التلقائي (UNSPECIFIED): ابدأ بالإعداد التلقائي. وقد تم ضبطه لتحقيق توازن جيد بين الجودة ووقت الاستجابة والتكلفة لمعظم حالات الاستخدام الشائعة.
• ‫LOW: يُستخدم في الحالات التي تكون فيها التكلفة ووقت الاستجابة من أهم العوامل، وتكون التفاصيل الدقيقة أقل أهمية.
• ‫MEDIUM / HIGH: يمكنك زيادة درجة الدقة عندما تتطلّب المهمة فهم التفاصيل المعقّدة في الوسائط. ويكون ذلك مطلوبًا في كثير من الأحيان لإجراء تحليل مرئي معقّد أو قراءة الرسوم البيانية أو فهم المستندات الكثيفة.
• ‫ULTRA HIGH: لا يتوفّر إلا لإعدادات كل جزء. يُنصح به لحالات استخدام معيّنة، مثل استخدام الكمبيوتر أو عندما يُظهر الاختبار تحسّنًا واضحًا مقارنةً بـ HIGH.
• التحكّم في كل جزء (Gemini 4 وGemini 3): يحسّن استخدام الرموز المميّزة. على سبيل المثال، في طلب يتضمّن صورًا متعددة، يمكنك استخدام HIGH لمخطّط بياني معقّد وLOW أو MEDIUM لصور سياقية أبسط.

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

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

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

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

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

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

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

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

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

• يتوفّر التعداد MediaResolution لجميع النماذج التي تتيح إدخال الوسائط.
• تختلف أعداد الرموز المميّزة المرتبطة بكل مستوى من مستويات التعداد بين نماذج Gemini 4 وGemini 3 وإصدارات Gemini السابقة.
• يمكن ضبط media_resolution على عناصر Part فردية في نموذجَي Gemini 4 وGemini 3.

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

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