وضوح رسانه

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

شما می‌توانید وضوح رسانه را برای اشیاء رسانه‌ای (موارد محتوا) در درخواست خود پیکربندی کنید (فقط Gemini 3).

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

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

from google import genai
from google.genai import types

client = genai.Client()

myfile = client.files.upload(file="path/to/image.jpg")

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input=[
        {"type": "text", "text": "Describe this image:"},
        {
            "type": "image",
            "uri": myfile.uri,
            "mime_type": myfile.mime_type,
            "resolution": "high"
        }
    ]
)
print(interaction.steps[-1].content[0].text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/image.jpg",
    config: { mimeType: "image/jpeg" },
  });

  const interaction = await ai.interactions.create({
    model: "gemini-3-flash-preview",
    input: [
      { type: "text", text: "Describe this image:" },
      {
        type: "image",
        uri: myfile.uri,
        mimeType: myfile.mimeType,
        resolution: "high"
      }
    ],
  });
  console.log(interaction.steps.at(-1).content[0].text);
}

await main();

# First upload the file using the Files API, then use the URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": [
      {"type": "text", "text": "Describe this image:"},
      {
        "type": "image",
        "uri": "YOUR_FILE_URI",
        "mime_type": "image/jpeg",
        "resolution": "high"
      }
    ]
  }'

مقادیر وضوح موجود

رابط برنامه‌نویسی نرم‌افزار Gemini سطوح زیر را برای وضوح رسانه تعریف می‌کند:

• unspecified : تنظیم پیش‌فرض. تعداد توکن‌ها برای این سطح بین Gemini 3 و مدل‌های قبلی Gemini به طور قابل توجهی متفاوت است.
• low : تعداد توکن‌های کمتر، که منجر به پردازش سریع‌تر و هزینه کمتر می‌شود، اما با جزئیات کمتر.
• medium : تعادلی بین جزئیات، هزینه و تأخیر.
• high : تعداد توکن‌های بالاتر، جزئیات بیشتری را برای کار با مدل فراهم می‌کند، اما به قیمت افزایش تأخیر و هزینه.
• ultra_high (فقط برای هر آیتم محتوایی): بالاترین تعداد توکن، مورد نیاز برای موارد استفاده خاص مانند استفاده از کامپیوتر .

توجه داشته باشید که high عملکرد بهینه را برای اکثر موارد استفاده فراهم می‌کند.

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

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

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

جمینی ۳ مدل

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

• پیش‌فرض ( unspecified ): با پیش‌فرض شروع کنید. این مقدار برای ایجاد تعادل مناسب بین کیفیت، تأخیر و هزینه برای اکثر موارد استفاده رایج تنظیم شده است.
• low : برای سناریوهایی استفاده می‌شود که هزینه و تأخیر از اهمیت بالایی برخوردارند و جزئیات دقیق اهمیت کمتری دارند.
• medium ​​/ high : وقتی وظیفه نیاز به درک جزئیات پیچیده در رسانه دارد، وضوح را افزایش دهید. این اغلب برای تجزیه و تحلیل بصری پیچیده، خواندن نمودار یا درک اسناد حجیم مورد نیاز است.
• ultra_high - فقط برای تنظیمات هر آیتم محتوایی در دسترس است. برای موارد استفاده خاص مانند استفاده از کامپیوتر یا مواردی که آزمایش، بهبود واضحی نسبت به high نشان می‌دهد، توصیه می‌شود.
• کنترل هر آیتم محتوا (Gemini 3): استفاده از توکن را بهینه می‌کند. برای مثال، در یک اعلان با چندین تصویر، برای یک نمودار پیچیده high و برای تصاویر متنی ساده‌تر low یا medium استفاده کنید.

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

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

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

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

• تنظیم resolution برای هر یک از آیتم‌های محتوا منحصراً برای مدل‌های Gemini 3 است.

مراحل بعدی

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