media_resolution 參數可決定分配給媒體輸入內容的權杖數量上限,藉此控管 Gemini API 處理圖片、影片和 PDF 文件等媒體輸入內容的方式,讓您在回覆品質、延遲時間和費用之間取得平衡。如要瞭解不同設定、預設值,以及這些設定與權杖的對應關係,請參閱「權杖計數」一節。
設定媒體解析度的方式有兩種:
每個部分的媒體解析度 (僅限 Gemini 3)
Gemini 3 可讓您在要求中為個別媒體物件設定媒體解析度,進而精細調整權杖用量。您可以在單一要求中混用解析度層級。舉例來說,複雜的圖表使用高解析度,簡單的背景圖片則使用低解析度。這項設定會覆寫特定零件的任何全域設定。如需預設設定,請參閱「權杖計數」一節。
Python
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)
JavaScript
// 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();
REST
# 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,為要求中的所有媒體部分設定預設解析度。所有多模態模型都支援這項功能。如果要求同時包含全域和每個部分的設定,則該特定項目的設定會優先。
Python
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)
JavaScript
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();
REST
# ... (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 API 定義了下列媒體解析度層級:
MEDIA_RESOLUTION_UNSPECIFIED:預設設定。Gemini 3 和舊版 Gemini 模型之間,這個層級的權杖數量差異很大。MEDIA_RESOLUTION_LOW:權杖數量較少,因此處理速度較快且成本較低,但詳細程度較低。MEDIA_RESOLUTION_MEDIUM:在詳細程度、費用和延遲時間之間取得平衡。MEDIA_RESOLUTION_HIGH:權杖數量較多,可為模型提供更多詳細資料,但延遲時間和費用會增加。- (即將推出)
MEDIA_RESOLUTION_ULTRA_HIGH:特定用途 (例如電腦使用) 需要的權杖數量上限。
每個層級產生的確切權杖數量取決於媒體類型 (圖片、影片、PDF) 和模型版本。
權杖數量
下表彙整各模型系列的每個 media_resolution 值和媒體類型的大約權杖數。
Gemini 3 模型
| MediaResolution | 圖片 | 影片 | |
MEDIA_RESOLUTION_UNSPECIFIED (預設)
|
1120 | 70 | 560 |
MEDIA_RESOLUTION_LOW
|
280 | 70 | 280 + 原生文字 |
MEDIA_RESOLUTION_MEDIUM
|
560 | 70 | 560 + 原生文字 |
MEDIA_RESOLUTION_HIGH
|
1120 | 280 | 1120 + 原生文字 |
Gemini 2.5 模型
| MediaResolution | 圖片 | 影片 | PDF (掃描) | PDF (原生) |
MEDIA_RESOLUTION_UNSPECIFIED (預設)
|
256 + Pan & Scan (~2048) | 256 | 256 + OCR | 256 + 原生文字 |
MEDIA_RESOLUTION_LOW
|
64 | 64 | 64 + OCR | 64 + 原生文字 |
MEDIA_RESOLUTION_MEDIUM
|
256 | 256 | 256 + OCR | 256 + 原生文字 |
MEDIA_RESOLUTION_HIGH
|
256 + Pan & Scan | 256 | 256 + OCR | 256 + 原生文字 |
選擇合適的解析度
- 預設 (
UNSPECIFIED):從預設值開始。經過微調,可在最常見的用途中,兼顧品質、延遲時間和成本。 LOW:適用於成本和延遲時間至關重要,但細部資訊較不重要的情境。MEDIUM/HIGH:如果工作需要瞭解媒體中的複雜細節,請提高解析度。這通常是複雜的視覺分析、圖表解讀或密集文件理解所需要的。- 逐部分控制 (Gemini 3):善用這項功能,盡量減少權杖用量。舉例來說,在含有多張圖片的提示中,使用
HIGH建立複雜的圖表,並使用LOW或MEDIUM建立較簡單的背景圖片。
建議設定
下表列出各支援媒體類型的建議媒體解析度設定。
| 媒體類型 | 建議設定 | 權杖上限 | 使用指南 |
| 圖片 | MEDIA_RESOLUTION_HIGH
|
1120 | 建議用於大多數圖像分析工作,確保最高品質。 |
| PDF 檔案 | MEDIA_RESOLUTION_MEDIUM
|
560 | 最適合用於瞭解文件內容,品質通常會在 medium 達到飽和。增加至 high 很少能改善標準文件的 OCR 結果。
|
| 影片 (一般) | MEDIA_RESOLUTION_LOW (或 MEDIA_RESOLUTION_MEDIUM)
|
70 (每幀) | 注意:對於影片,low 和 medium 設定會視為相同 (70 個權杖),以最佳化情境使用情形。這足以應付大多數的動作辨識和描述工作。
|
| 影片 (文字內容較多) | MEDIA_RESOLUTION_HIGH
|
280 (每格) | 只有在用途涉及讀取密集文字 (OCR) 或影片影格中的細節時,才需要此功能。 |
請務必測試及評估不同解析度設定對特定應用程式的影響,找出品質、延遲和成本之間的最佳取捨。
版本相容性摘要
- 所有支援媒體輸入的模型都適用
MediaResolution列舉。 - 每個列舉層級的相關權杖計數在 Gemini 3 模型和先前的 Gemini 版本之間有所不同。
- 在個別
Part物件上設定media_resolution僅適用於 Gemini 3 模型。