وضوح رسانه

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

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

وضوح رسانه‌ای برای هر بخش (فقط Gemini 3)

Gemini 3 به شما امکان می‌دهد وضوح رسانه را برای اشیاء رسانه‌ای منفرد در درخواست خود تنظیم کنید و بهینه‌سازی دقیقی از استفاده از توکن ارائه می‌دهد. می‌توانید سطوح وضوح را در یک درخواست واحد ترکیب کنید. به عنوان مثال، استفاده از وضوح بالا برای یک نمودار پیچیده و وضوح پایین برای یک تصویر متنی ساده. این تنظیم هرگونه پیکربندی جهانی را برای یک بخش خاص لغو می‌کند. برای تنظیمات پیش‌فرض، به بخش تعداد توکن‌ها مراجعه کنید.

پایتون

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)

جاوا اسکریپت

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

استراحت

# 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 یک وضوح پیش‌فرض برای تمام بخش‌های رسانه در یک درخواست تنظیم کنید. این توسط همه مدل‌های چندوجهی پشتیبانی می‌شود. اگر یک درخواست شامل تنظیمات سراسری و تنظیمات هر بخش باشد، تنظیمات هر بخش برای آن مورد خاص اولویت دارد.

پایتون

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)

جاوا اسکریپت

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

استراحت

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

  • MEDIA_RESOLUTION_UNSPECIFIED : تنظیم پیش‌فرض. تعداد توکن‌ها برای این سطح بین Gemini 3 و مدل‌های قبلی Gemini به طور قابل توجهی متفاوت است.
  • MEDIA_RESOLUTION_LOW : تعداد توکن‌های کمتر، در نتیجه پردازش سریع‌تر و هزینه کمتر، اما با جزئیات کمتر.
  • MEDIA_RESOLUTION_MEDIUM : تعادلی بین جزئیات، هزینه و تأخیر.
  • MEDIA_RESOLUTION_HIGH : تعداد توکن بالاتر، جزئیات بیشتری را برای کار با مدل ارائه می‌دهد، اما به قیمت افزایش تأخیر و هزینه.
  • ( به زودی ) MEDIA_RESOLUTION_ULTRA_HIGH : بالاترین تعداد توکن مورد نیاز برای موارد استفاده خاص مانند استفاده از کامپیوتر.

تعداد دقیق توکن‌های تولید شده برای هر یک از این سطوح، هم به نوع رسانه (تصویر، ویدئو، PDF) و هم به نسخه مدل بستگی دارد.

شمارش توکن‌ها

جداول زیر تعداد تقریبی توکن‌ها را برای هر مقدار media_resolution و نوع رسانه در هر خانواده مدل خلاصه می‌کنند.

مدل‌های جمینی ۳

وضوح رسانه‌ای تصویر ویدئو پی دی اف
MEDIA_RESOLUTION_UNSPECIFIED (پیش‌فرض) ۱۱۲۰ ۷۰ ۵۶۰
MEDIA_RESOLUTION_LOW ۲۸۰ ۷۰ ۲۸۰ + متن بومی
MEDIA_RESOLUTION_MEDIUM ۵۶۰ ۷۰ ۵۶۰ + متن بومی
MEDIA_RESOLUTION_HIGH ۱۱۲۰ ۲۸۰ ۱۱۲۰ + متن بومی

مدل‌های جمینی ۲.۵

وضوح رسانه‌ای تصویر ویدئو پی‌دی‌اف (اسکن شده) پی‌دی‌اف (بومی)
MEDIA_RESOLUTION_UNSPECIFIED (پیش‌فرض) ۲۵۶ + پیمایش و اسکن (~۲۰۴۸) ۲۵۶ ۲۵۶ + OCR ۲۵۶ + متن بومی
MEDIA_RESOLUTION_LOW ۶۴ ۶۴ ۶۴ + OCR ۶۴ + متن بومی
MEDIA_RESOLUTION_MEDIUM ۲۵۶ ۲۵۶ ۲۵۶ + OCR ۲۵۶ + متن بومی
MEDIA_RESOLUTION_HIGH ۲۵۶ + پان و اسکن ۲۵۶ ۲۵۶ + OCR ۲۵۶ + متن بومی

انتخاب رزولوشن مناسب

  • پیش‌فرض ( UNSPECIFIED ): با پیش‌فرض شروع کنید. این مقدار برای ایجاد تعادل خوبی بین کیفیت، تأخیر و هزینه برای اکثر موارد استفاده رایج تنظیم شده است.
  • LOW : برای سناریوهایی استفاده می‌شود که هزینه و تأخیر از اهمیت بالایی برخوردارند و جزئیات دقیق اهمیت کمتری دارند.
  • MEDIUM ​​/ HIGH : وقتی وظیفه نیاز به درک جزئیات پیچیده در رسانه دارد، وضوح را افزایش دهید. این اغلب برای تجزیه و تحلیل بصری پیچیده، خواندن نمودار یا درک اسناد حجیم مورد نیاز است.
  • کنترل هر بخش (Gemini 3): از این قابلیت برای بهینه‌سازی استفاده از توکن استفاده کنید. برای مثال، در یک اعلان با چندین تصویر، برای یک نمودار پیچیده HIGH و برای تصاویر متنی ساده‌تر LOW یا MEDIUM استفاده کنید.

تنظیمات توصیه شده

در زیر تنظیمات وضوح رسانه توصیه شده برای هر نوع رسانه پشتیبانی شده فهرست شده است.

نوع رسانه تنظیمات توصیه شده حداکثر توکن‌ها راهنمای استفاده
تصاویر MEDIA_RESOLUTION_HIGH ۱۱۲۰ برای اطمینان از حداکثر کیفیت، برای اکثر وظایف تحلیل تصویر توصیه می‌شود.
فایل‌های PDF MEDIA_RESOLUTION_MEDIUM ۵۶۰ برای درک اسناد بهینه است؛ کیفیت معمولاً در medium ​​اشباع می‌شود. افزایش به high به ندرت نتایج OCR را برای اسناد استاندارد بهبود می‌بخشد.
ویدئو (عمومی) MEDIA_RESOLUTION_LOW (یا MEDIA_RESOLUTION_MEDIUM ) ۷۰ (در هر فریم) توجه: برای ویدیو، تنظیمات low و medium ​​​​به طور یکسان (70 توکن) در نظر گرفته می‌شوند تا استفاده از متن بهینه شود. این برای اکثر وظایف تشخیص و توصیف عمل کافی است.
ویدئو (پر از متن) MEDIA_RESOLUTION_HIGH ۲۸۰ (در هر فریم) فقط زمانی مورد نیاز است که مورد استفاده شامل خواندن متن‌های متراکم (OCR) یا جزئیات کوچک در فریم‌های ویدیویی باشد.

همیشه تأثیر تنظیمات مختلف وضوح تصویر را بر روی کاربرد خاص خود آزمایش و ارزیابی کنید تا بهترین تعادل بین کیفیت، تأخیر و هزینه را پیدا کنید.

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

  • شمارشگر MediaResolution برای همه مدل‌هایی که از ورودی رسانه پشتیبانی می‌کنند، در دسترس است.
  • تعداد توکن‌های مرتبط با هر سطح شمارشی بین مدل‌های Gemini 3 و نسخه‌های قبلی Gemini متفاوت است .
  • تنظیم media_resolution روی اشیاء Part به صورت جداگانه منحصر به مدل‌های Gemini 3 است.

مراحل بعدی