ความละเอียดของสื่อ

พารามิเตอร์ media_resolution จะควบคุมวิธีที่ Gemini API ประมวลผลอินพุตสื่อ เช่น รูปภาพ วิดีโอ เสียง และเอกสาร PDF โดยกำหนดจำนวนโทเค็นสูงสุด ที่จัดสรรไว้สำหรับอินพุตสื่อ ซึ่งช่วยให้คุณปรับสมดุลคุณภาพการตอบสนองกับเวลาในการตอบสนองและค่าใช้จ่ายได้ แม้ว่าอินพุตภาพและเอกสารจะปรับขนาดการจัดสรรโทเค็นตามการตั้งค่าความละเอียด แต่อินพุตเสียงจะมีการแปลงเป็นโทเค็นในอัตราคงที่ต่อวินาทีในทุกระดับความละเอียด สำหรับการตั้งค่าต่างๆ ค่าเริ่มต้น และวิธีที่การตั้งค่าเหล่านั้นสอดคล้องกับโทเค็น โปรดดูส่วน จำนวนโทเค็น

คุณกำหนดค่าความละเอียดของสื่อได้ 2 วิธี ดังนี้

• ต่อส่วน (โมเดล Gemini 4 และ Gemini 3)

• ทั่วโลกสำหรับคำขอ generateContent ทั้งหมด (โมเดลมัลติโมดัลทั้งหมด)

ความละเอียดของสื่อต่อส่วน (Gemini 4 และ Gemini 3)

Gemini 4 และ Gemini 3 ช่วยให้คุณกำหนดความละเอียดของสื่อสำหรับออบเจ็กต์สื่อแต่ละรายการภายในคำขอได้ ซึ่งช่วยให้คุณเพิ่มประสิทธิภาพการใช้โทเค็นได้อย่างละเอียด คุณสามารถผสมระดับความละเอียดในคำขอเดียวได้ เช่น ใช้ความละเอียดสูงสำหรับแผนภาพที่ซับซ้อน และใช้ความละเอียดต่ำสำหรับรูปภาพตามบริบท การตั้งค่านี้จะลบล้างการกำหนดค่าส่วนกลางสำหรับส่วนที่เฉพาะเจาะจง สำหรับการตั้งค่าเริ่มต้น โปรดดูส่วนจำนวนโทเค็น

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-4-argon'

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: '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-4-argon';
    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-4-argon"

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 ซึ่งโมเดลมัลติโมดัลทั้งหมดรองรับ หากคำขอ มีการตั้งค่าทั้งส่วนกลางและต่อส่วนการตั้งค่าต่อส่วนจะมีความสำคัญเหนือกว่าสำหรับรายการนั้นๆ

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.8-flash',
    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.8-flash',
      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.8-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

โมเดล Gemini 2.5

การเลือกความละเอียดที่เหมาะสม

• ค่าเริ่มต้น (UNSPECIFIED): เริ่มต้นด้วยค่าเริ่มต้น ซึ่งปรับแต่งมาเพื่อให้ได้ความสมดุลที่ดีระหว่างคุณภาพ เวลาในการตอบสนอง และค่าใช้จ่ายสำหรับกรณีการใช้งานที่พบบ่อยที่สุด
• LOW: ใช้ในสถานการณ์ที่ค่าใช้จ่ายและเวลาในการตอบสนองมีความสำคัญสูงสุด และรายละเอียดที่ละเอียดมีความสำคัญน้อยกว่า
• MEDIUM / HIGH: เพิ่มความละเอียดเมื่องานต้องใช้ความเข้าใจรายละเอียดที่ซับซ้อนภายในสื่อ ซึ่งมักจำเป็นสำหรับการวิเคราะห์ภาพที่ซับซ้อน การอ่านแผนภูมิ หรือความเข้าใจเอกสารที่มีข้อมูลหนาแน่น
• ULTRA HIGH - ใช้ได้กับการตั้งค่าต่อส่วนเท่านั้น แนะนำสำหรับกรณีการใช้งานที่เฉพาะเจาะจง เช่น การใช้คอมพิวเตอร์ หรือในกรณีที่การทดสอบแสดงให้เห็นถึงการปรับปรุงที่ชัดเจนเมื่อเทียบกับ HIGH
• การควบคุมต่อส่วน (Gemini 4 และ Gemini 3): เพิ่มประสิทธิภาพการใช้โทเค็น เช่น ในพรอมต์ที่มีรูปภาพหลายรายการ ให้ใช้ HIGH สำหรับแผนภาพที่ซับซ้อน และใช้ LOW หรือ MEDIUM สำหรับรูปภาพตามบริบทที่ง่ายกว่า

การตั้งค่าที่แนะนำ

รายการต่อไปนี้แสดงการตั้งค่าความละเอียดของสื่อที่แนะนำสำหรับสื่อแต่ละประเภทที่รองรับ

ทดสอบและประเมินผลกระทบของการตั้งค่าความละเอียดต่างๆ ในแอปพลิเคชันที่เฉพาะเจาะจงเสมอ เพื่อหาจุดสมดุลที่ดีที่สุดระหว่างคุณภาพ เวลาในการตอบสนอง และค่าใช้จ่าย

ความสัมพันธ์กับโหมดการประมวลผลวิดีโอ

พารามิเตอร์ media_resolution และการประมวลผลจะควบคุมอินพุตวิดีโอในด้านต่างๆ ดังนี้

• media_resolution ควบคุมความละเอียด ของแต่ละเฟรม (จำนวนโทเค็นต่อเฟรม)
• processing / media_processing ควบคุมเนื้อหาใดจากวิดีโอ ที่โหลดลงในบริบท

คุณสามารถตั้งค่าทั้ง 2 อย่างในอินพุตวิดีโอเดียวกันได้ เช่น คุณอาจใช้การประมวลผลแบบเอเจนต์ที่มีความละเอียดของสื่อต่ำเพื่อลดการใช้โทเค็นทั้งหมดสำหรับวิดีโอขนาดยาว

โปรดดูรายละเอียดเกี่ยวกับโหมดการประมวลผลวิดีโอในคู่มือความเข้าใจวิดีโอแบบเอเจนต์

สรุปความเข้ากันได้ของเวอร์ชัน

• Enum MediaResolution ใช้ได้กับโมเดลทั้งหมดที่รองรับอินพุตสื่อ
• จำนวนโทเค็นที่เชื่อมโยงกับแต่ละระดับ Enum จะแตกต่างกัน ระหว่างโมเดล Gemini 4 / Gemini 3 กับ Gemini เวอร์ชันก่อนหน้า
• ระบบรองรับ การตั้งค่า media_resolution ในออบเจ็กต์ Part แต่ละรายการใน โมเดล Gemini 4 และ Gemini 3

ขั้นตอนถัดไป

• ดูข้อมูลเพิ่มเติมเกี่ยวกับความสามารถมัลติโมดัลของ Gemini API ใน คู่มือความเข้าใจรูปภาพ, ความเข้าใจวิดีโอ, ความเข้าใจเสียง และ ความเข้าใจเอกสาร