وضوح رسانه

پارامتر media_resolution نحوه پردازش ورودی‌های رسانه‌ای مانند تصاویر، ویدیوها، صدا، و اسناد PDF توسط Gemini API را با تعیین حداکثر تعداد نشان‌های اختصاص‌داده‌شده به ورودی‌های رسانه‌ای کنترل می‌کند و به شما امکان می‌دهد کیفیت پاسخ را دربرابر تأخیر و هزینه متعادل کنید. درحالی‌که ورودی‌های تصویری و نوشتاری تخصیص نشان را براساس تنظیمات وضوح مقیاس‌بندی می‌کنند، ورودی‌های صوتی با نرخ ثابتی در ثانیه در تمام سطوح وضوح نشان‌گذاری می‌شوند. برای تنظیمات مختلف، مقادیر پیش‌فرض، و نحوه مطابقت آن‌ها با کدها، به بخش تعداد کدها مراجعه کنید.

می‌توانید وضوح رسانه را به دو روش پیکربندی کنید:

• به‌ازای هر بخش (مدل‌های 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» سطوح زیر را برای وضوح رسانه تعریف می‌کند:

• 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 کنترل می‌کند کدام محتوای ویدیو در بافت بارگیری شود.

می‌توانید هر دو را روی یک ورودی ویدیو تنظیم کنید. برای مثال، می‌توانید از پردازش عاملی با وضوح رسانه پایین استفاده کنید تا کل استفاده از نشانه را برای یک ویدیو طولانی به حداقل برسانید.

برای جزئیات بیشتر درباره حالت‌های پردازش ویدیو، به راهنمای درک ویدیو با Agentic مراجعه کنید.

خلاصه سازگاری نسخه

• عدد ثابت MediaResolution برای همه مدل‌هایی که از ورودی رسانه پشتیبانی می‌کنند دردسترس است.
• تعداد داده‌واحد مرتبط با هر سطح شمارشی بین مدل‌های Gemini 4 / Gemini 3 و نسخه‌های قبلی Gemini متفاوت است.
• تنظیم media_resolution روی هریک از Part اشیا در مدل‌های Gemini 4 و Gemini 3 پشتیبانی می‌شود.

مراحل بعدی

• درباره قابلیت‌های چندوجهی Gemini API در راهنماهای درک تصویر، درک ویدیو، درک صدا، و درک سند بیشتر بدانید.