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

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

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

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

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

Python

from google import genai
from google.genai import types

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

# 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-pro-preview'

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

JavaScript

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

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

REST

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

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

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

Python

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

JavaScript

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

REST

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

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

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

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

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

نماذج Gemini 3

MediaResolution صورة الفيديو PDF
MEDIA_RESOLUTION_UNSPECIFIED (تلقائي) 1120 70 560
MEDIA_RESOLUTION_LOW 280 70 ‫280 + نص إعلاني مدمج
MEDIA_RESOLUTION_MEDIUM 560 70 ‫560 + نص إعلاني على المنصة نفسها
MEDIA_RESOLUTION_HIGH 1120 280 ‫1120 + نص إعلاني مدمج

نماذج Gemini 2.5

MediaResolution صورة الفيديو ملف PDF (ممسوح ضوئيًا) ملف PDF (مدمَج مع المحتوى)
MEDIA_RESOLUTION_UNSPECIFIED (تلقائي) ‫256 + Pan & Scan (حوالي 2048) 256 ‫256 + التعرّف البصري على الأحرف ‫256 + نص إعلاني أصلي
MEDIA_RESOLUTION_LOW 64 64 ‫64 + التعرّف البصري على الأحرف ‫64 + نص إعلاني على المنصة نفسها
MEDIA_RESOLUTION_MEDIUM 256 256 ‫256 + التعرّف البصري على الأحرف ‫256 + نص إعلاني أصلي
MEDIA_RESOLUTION_HIGH ‫256 + Pan & Scan 256 ‫256 + التعرّف البصري على الأحرف ‫256 + نص إعلاني أصلي

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

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

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

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

نوع الوسائط الإعدادات المقترَحة الحد الأقصى للرموز المميزة إرشادات الاستخدام
الصور MEDIA_RESOLUTION_HIGH 1120 يُنصح باستخدامها لمعظم مهام تحليل الصور لضمان الحصول على أعلى جودة.
ملفات PDF MEDIA_RESOLUTION_MEDIUM 560 الأفضل لفهم المستندات، وعادةً ما تصل الجودة إلى الحدّ الأقصى عند medium. لا تؤدي الزيادة إلى high في أغلب الأحيان إلى تحسين نتائج التعرّف البصري على الأحرف للمستندات العادية.
الفيديو (عام) MEDIA_RESOLUTION_LOW (أو MEDIA_RESOLUTION_MEDIUM) ‫70 (لكل إطار) ملاحظة: بالنسبة إلى الفيديو، يتم التعامل مع إعدادات low وmedium بشكل مماثل (70 رمزًا مميزًا) لتحسين استخدام السياق. وهذا يكفي لمعظم مهام التعرّف على الإجراءات ووصفها.
الفيديو (يحتوي على الكثير من النصوص) MEDIA_RESOLUTION_HIGH ‫280 (لكل إطار) يجب توفُّرها فقط عندما تتضمّن حالة الاستخدام قراءة نص كثيف (التعرّف البصري على الأحرف) أو تفاصيل صغيرة ضمن لقطات الفيديو.

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

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

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

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