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

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

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

• لكل جزء (Gemini 3 فقط)

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

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

يتيح لك 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-3.1-pro-preview'

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-3.1-pro-preview';
    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-3.1-pro-preview"

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 3): يحسِّن استخدام الرموز المميزة. على سبيل المثال، في طلب يتضمّن صورًا متعددة، استخدِم HIGH لرسم تخطيطي معقّد وLOW أو MEDIUM لصور سياقية أبسط.

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

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

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

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

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

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

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

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

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

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

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

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