وضوح رسانه

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

می‌توانید وضوح رسانه را برای هریک از عناصر رسانه‌ای (محتوا) در درخواستتان پیکربندی کنید (مدل‌های Gemini 4 و Gemini 3).

وضوح رسانه برای هر مورد محتوا (مدل‌های Gemini 4 و Gemini 3)

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

Python

from google import genai

client = genai.Client()

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

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Describe this image:"},
        {
            "type": "image",
            "uri": myfile.uri,
            "mime_type": myfile.mime_type,
            "resolution": "high"
        }
    ]
)
print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

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

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "text", text: "Describe this image:" },
      {
        type: "image",
        uri: myfile.uri,
        mime_type: myfile.mimeType,
        resolution: "high"
      }
    ],
  });
  console.log(interaction.output_text);
}

await main();

جاوا

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Describe the details in this high-resolution image.").build();
Content imageContent =
    ImageContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/image/scones.jpg")
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

رفتن

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/image.jpg", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Describe the details in this high-resolution image.",
                }),
                interactions.NewContent(interactions.ImageContent{
                    URI:        genai.Ptr(uploadedFile.URI),
                    MimeType:   interactions.ImageContentMimeType(uploadedFile.MIMEType).ToPointer(),
                    Resolution: interactions.MediaResolutionHigh.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

# 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.8-flash",
    "input": [
      {"type": "text", "text": "Describe this image:"},
      {
        "type": "image",
        "uri": "YOUR_FILE_URI",
        "mime_type": "image/jpeg",
        "resolution": "high"
      }
    ]
  }'

مقادیر وضوح دردسترس

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

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

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

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

تعداد داده‌واحد

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

مدل‌های Gemini 4 و Gemini 3

MediaResolution تصویر ویدیو صوتی PDF
‫unspecified (پیش‌فرض) 1120 70 ‫۲۵ (در ثانیه) 560
low 280 70 ‫۲۵ (در ثانیه) ‫۲۸۰ + نوشتار تعبیه‌شده
medium 560 70 ‫۲۵ (در ثانیه) ‫۵۶۰ + نوشتار تعبیه‌شده
high 1120 280 ‫۲۵ (در ثانیه) ‫۱۱۲۰ + نوشتار تعبیه‌شده
ultra_high 2240 موجود نیست موجود نیست موجود نیست

انتخاب وضوح مناسب

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

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

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

نوع رسانه تنظیمات توصیه‌شده حداکثر داده‌واحدها راهنمای استفاده
تصاویر high 1120 برای اکثر تکالیف تجزیه‌وتحلیل تصویر توصیه می‌شود تا حداکثر کیفیت تضمین شود.
PDF medium 560 بهترین گزینه برای درک سند؛ کیفیت معمولاً در medium اشباع می‌شود. افزایش به high به‌ندرت نتایج «تبدیل تصویر به نوشتار» را برای سندهای استاندارد بهبود می‌دهد.
ویدیو (عمومی) low (یا medium) ۷۰ (برای هر قاب) توجه: برای ویدیو، تنظیمات low و medium به‌طور یکسان (۷۰ واحد) برای بهینه‌سازی استفاده از زمینه درنظر گرفته می‌شوند. این مقدار برای اکثر تکالیف تشخیص و شرح کنش کافی است.
ویدیو (نوشتار زیاد) high ۲۸۰ (برای هر قاب) فقط زمانی لازم است که مورد استفاده شامل خواندن نوشتار متراکم (OCR) یا جزئیات کوچک در فریم‌های ویدیو باشد.
صدا ‫unspecified (پیش‌فرض) ‫۲۵ (در ثانیه) صدا با نرخ ثابت ۲۵ کد در ثانیه در تمام تنظیمات وضوح پشتیبانی‌شده (unspecified،‏ low،‏ medium، و high) کدبندی می‌شود.

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

رابطه با حالت‌های پردازش ویدیو

پارامترهای media_resolution و پردازش جنبه‌های مختلف ورودی ویدیو را کنترل می‌کنند:

  • media_resolution وضوح هر قاب (تعداد نشان‌برهای هر قاب) را کنترل می‌کند.
  • ‫processing / media_processing کنترل می‌کند کدام محتوای ویدیو در بافت بارگیری شود.

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

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

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

  • تنظیم resolution در موارد محتوای جداگانه در مدل‌های Gemini 4 و Gemini 3 پشتیبانی می‌شود.

مراحل بعدی