พารามิเตอร์ media_resolution จะควบคุมวิธีที่ Gemini API ประมวลผลอินพุตสื่อ เช่น รูปภาพ วิดีโอ และเอกสาร PDF โดยกำหนดจำนวนโทเค็นสูงสุด ที่จัดสรรไว้สำหรับอินพุตสื่อ ซึ่งช่วยให้คุณปรับสมดุลคุณภาพของคำตอบกับเวลาในการตอบสนองและค่าใช้จ่ายได้ ดูการตั้งค่าต่างๆ ค่าเริ่มต้น และวิธีที่การตั้งค่าเหล่านั้นสอดคล้องกับโทเค็นได้ในส่วนจำนวนโทเค็น
คุณกำหนดค่าความละเอียดของสื่อได้ 2 วิธี ดังนี้
ความละเอียดของสื่อต่อส่วน (Gemini 3 เท่านั้น)
Gemini 3 ช่วยให้คุณกำหนดความละเอียดของสื่อสำหรับออบเจ็กต์สื่อแต่ละรายการภายในคำขอได้ ซึ่งช่วยให้เพิ่มประสิทธิภาพการใช้งานโทเค็นได้อย่างละเอียด คุณสามารถผสมระดับความละเอียดในคำขอเดียวได้ เช่น ใช้ความละเอียดสูงสำหรับแผนภาพที่ซับซ้อน และความละเอียดต่ำสำหรับรูปภาพบริบทอย่างง่าย การตั้งค่านี้จะลบล้างการกำหนดค่าส่วนกลางสำหรับส่วนที่เฉพาะเจาะจง ดูการตั้งค่าเริ่มต้นได้ในส่วนจำนวนโทเค็น
Python
from google import genai
from google.genai import types
# The media_resolution parameter for parts is available in the v1beta API version.
client = genai.Client(
http_options={
'api_version': 'v1beta',
}
)
# 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)
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: 'v1beta' } });
// 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();
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.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/v1beta/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-3.6-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-3.6-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-3.6-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(ต่อส่วนเท่านั้น): จำนวนโทเค็นสูงสุด ซึ่งจำเป็นสำหรับกรณีการใช้งานที่เฉพาะเจาะจง เช่น การใช้คอมพิวเตอร์
โปรดทราบว่า MEDIA_RESOLUTION_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 + ข้อความเนทีฟ |
MEDIA_RESOLUTION_ULTRA_HIGH
|
2240 | ไม่มี | ไม่มี |
โมเดล Gemini 2.5
| MediaResolution | รูปภาพ | วิดีโอ | PDF (สแกน) | PDF (เนทีฟ) |
MEDIA_RESOLUTION_UNSPECIFIED (ค่าเริ่มต้น)
|
256 + แพนและสแกน (~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 + แพนและสแกน | 256 | 256 + OCR | 256 + ข้อความเนทีฟ |
การเลือกความละเอียดที่เหมาะสม
- ค่าเริ่มต้น (
UNSPECIFIED): เริ่มต้นด้วยค่าเริ่มต้น ซึ่งได้รับการปรับแต่งให้มีความสมดุลที่ดีระหว่างคุณภาพ เวลาในการตอบสนอง และค่าใช้จ่ายสำหรับกรณีการใช้งานที่พบบ่อยที่สุด LOW: ใช้ในสถานการณ์ที่ค่าใช้จ่ายและเวลาในการตอบสนองมีความสำคัญสูงสุด และรายละเอียดที่ละเอียดมีความสำคัญน้อยกว่าMEDIUM/HIGH: เพิ่มความละเอียดเมื่องานต้องใช้ความเข้าใจรายละเอียดที่ซับซ้อนภายในสื่อ ซึ่งมักจำเป็นสำหรับการวิเคราะห์ภาพที่ซับซ้อน การอ่านแผนภูมิ หรือความเข้าใจเอกสารที่มีข้อมูลหนาแน่นULTRA HIGH- ใช้ได้กับการตั้งค่าต่อส่วนเท่านั้น แนะนำสำหรับกรณีการใช้งานที่เฉพาะเจาะจง เช่น การใช้คอมพิวเตอร์ หรือกรณีที่การทดสอบแสดงให้เห็นถึงการปรับปรุงที่ชัดเจนเมื่อเทียบกับHIGH- การควบคุมต่อส่วน (Gemini 3): เพิ่มประสิทธิภาพการใช้งานโทเค็น เช่น ในพรอมต์ที่มีรูปภาพหลายรูป ให้ใช้
HIGHสำหรับแผนภาพที่ซับซ้อน และLOWหรือMEDIUMสำหรับรูปภาพบริบทที่ง่ายกว่า
การตั้งค่าที่แนะนำ
รายการต่อไปนี้แสดงการตั้งค่าความละเอียดของสื่อที่แนะนำสำหรับสื่อแต่ละประเภทที่รองรับ
| ประเภทสื่อ | การตั้งค่าที่แนะนำ | โทเค็นสูงสุด | คำแนะนำการใช้งาน |
| Google รูปภาพ | MEDIA_RESOLUTION_HIGH
|
1120 | แนะนำสำหรับงานวิเคราะห์รูปภาพส่วนใหญ่เพื่อให้ได้คุณภาพสูงสุด |
MEDIA_RESOLUTION_MEDIUM
|
560 | เหมาะที่สุดสำหรับความเข้าใจเอกสาร โดยคุณภาพจะอิ่มตัวที่ medium โดยทั่วไป การเพิ่มเป็น high ไม่ค่อยปรับปรุงผลลัพธ์ OCR สำหรับเอกสารมาตรฐาน
|
|
| วิดีโอ (ทั่วไป) | MEDIA_RESOLUTION_LOW (หรือ MEDIA_RESOLUTION_MEDIUM)
|
70 (ต่อเฟรม) | หมายเหตุ: สำหรับวิดีโอ ระบบจะถือว่าการตั้งค่า low และ medium เหมือนกัน (70 โทเค็น) เพื่อเพิ่มประสิทธิภาพการใช้งานบริบท ซึ่งเพียงพอสำหรับงานการจดจำและการอธิบายการกระทำส่วนใหญ่
|
| วิดีโอ (มีข้อความจำนวนมาก) | MEDIA_RESOLUTION_HIGH
|
280 (ต่อเฟรม) | จำเป็นเฉพาะเมื่อกรณีการใช้งานเกี่ยวข้องกับการอ่านข้อความที่มีข้อมูลหนาแน่น (OCR) หรือรายละเอียดเล็กๆ ภายในเฟรมวิดีโอ |
ทดสอบและประเมินผลกระทบของการตั้งค่าความละเอียดต่างๆ ในแอปพลิเคชันที่เฉพาะเจาะจงเสมอ เพื่อค้นหาความสมดุลที่ดีที่สุดระหว่างคุณภาพ เวลาในการตอบสนอง และค่าใช้จ่าย
ข้อมูลสรุปความเข้ากันได้ของเวอร์ชัน
- Enum
MediaResolutionใช้ได้กับโมเดลทั้งหมดที่รองรับอินพุตสื่อ - จำนวนโทเค็นที่เชื่อมโยงกับแต่ละระดับ Enum จะแตกต่างกัน ระหว่างโมเดล Gemini 3 กับ Gemini เวอร์ชันก่อนหน้า
- การตั้งค่า
media_resolutionในออบเจ็กต์Partแต่ละรายการใช้ได้กับโมเดล Gemini 3 เท่านั้น
ขั้นตอนถัดไป
- ดูข้อมูลเพิ่มเติมเกี่ยวกับความสามารถในการประมวลผลข้อมูลหลายรูปแบบของ Gemini API ได้ใน คำแนะนำการทำความเข้าใจรูปภาพ ความเข้าใจวิดีโอ และ ความเข้าใจเอกสาร