وضوح رسانه
The media_resolution parameter controls how the Gemini API processes media inputs like images, videos, and PDF documents by determining the maximum number of tokens allocated for media inputs, allowing you to balance response quality against latency and cost. For different settings, default values and how they correspond to tokens, see the Token counts section.
شما میتوانید وضوح رسانه را به دو روش پیکربندی کنید:
به ازای هر قسمت (فقط جمینی ۳)
به صورت سراسری برای کل درخواست
generateContent(تمام مدلهای چندوجهی)
وضوح رسانهای برای هر بخش (فقط 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.1-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.1-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.1-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
قطعنامه رسانهای جهانی
You can set a default resolution for all media parts in a request using the GenerationConfig . This is supported by all multimodal models. If a request includes both global and per-part settings , the per-part setting takes precedence for that specific item.
پایتون
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-flash-preview',
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-flash-preview',
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-flash-preview: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 و نوع رسانه در هر خانواده مدل خلاصه میکنند.
جمینی ۳ مدل
| وضوح رسانهای | تصویر | ویدئو | پی دی اف |
MEDIA_RESOLUTION_UNSPECIFIED (پیشفرض) | ۱۱۲۰ | ۷۰ | ۵۶۰ |
MEDIA_RESOLUTION_LOW | ۲۸۰ | ۷۰ | ۲۸۰ + متن بومی |
MEDIA_RESOLUTION_MEDIUM | ۵۶۰ | ۷۰ | ۵۶۰ + متن بومی |
MEDIA_RESOLUTION_HIGH | ۱۱۲۰ | ۲۸۰ | ۱۱۲۰ + متن بومی |
MEDIA_RESOLUTION_ULTRA_HIGH | ۲۲۴۰ | ناموجود | ناموجود |
مدلهای جمینی ۲.۵
| وضوح رسانهای | تصویر | ویدئو | پیدیاف (اسکن شده) | پیدیاف (بومی) |
MEDIA_RESOLUTION_UNSPECIFIED (پیشفرض) | ۲۵۶ + پیمایش و اسکن (~۲۰۴۸) | ۲۵۶ | ۲۵۶ + OCR | ۲۵۶ + متن بومی |
MEDIA_RESOLUTION_LOW | ۶۴ | ۶۴ | ۶۴ + OCR | ۶۴ + متن بومی |
MEDIA_RESOLUTION_MEDIUM | ۲۵۶ | ۲۵۶ | ۲۵۶ + OCR | ۲۵۶ + متن بومی |
MEDIA_RESOLUTION_HIGH | ۲۵۶ + پان و اسکن | ۲۵۶ | ۲۵۶ + OCR | ۲۵۶ + متن بومی |
انتخاب رزولوشن مناسب
- پیشفرض (
UNSPECIFIED): با پیشفرض شروع کنید. این مقدار برای ایجاد تعادل خوبی بین کیفیت، تأخیر و هزینه برای اکثر موارد استفاده رایج تنظیم شده است. -
LOW: برای سناریوهایی استفاده میشود که هزینه و تأخیر از اهمیت بالایی برخوردارند و جزئیات دقیق اهمیت کمتری دارند. -
MEDIUM/HIGH: Increase the resolution when the task requires understanding intricate details within the media. This is often needed for complex visual analysis, chart reading, or dense document comprehension. -
ULTRA HIGH- فقط برای تنظیمات هر قطعه موجود است. برای موارد استفاده خاص مانند استفاده از کامپیوتر یا مواردی که آزمایش، بهبود واضحی نسبت به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 است.