Độ phân giải nội dung nghe nhìn

Tham số media_resolution kiểm soát cách Gemini API xử lý thông tin đầu vào đa phương tiện như hình ảnh, video và tài liệu PDF bằng cách xác định số lượng token tối đa được phân bổ cho thông tin đầu vào đa phương tiện, cho phép bạn cân bằng chất lượng phản hồi với độ trễ và chi phí. Để biết các chế độ cài đặt khác nhau, giá trị mặc định và cách các giá trị này tương ứng với mã thông báo, hãy xem phần Số lượng mã thông báo.

Bạn có thể định cấu hình độ phân giải của nội dung đa phương tiện theo 2 cách:

• Theo từng phần (chỉ Gemini 3)

• Trên toàn cầu cho toàn bộ yêu cầu generateContent (tất cả các mô hình đa phương thức)

Độ phân giải của nội dung đa phương tiện theo từng phần (chỉ Gemini 3)

Gemini 3 cho phép bạn đặt độ phân giải của nội dung đa phương tiện cho từng đối tượng nội dung đa phương tiện trong yêu cầu, giúp tối ưu hoá mức sử dụng token một cách chi tiết. Bạn có thể kết hợp các mức độ phân giải trong một yêu cầu. Ví dụ: sử dụng độ phân giải cao cho một sơ đồ phức tạp và độ phân giải thấp cho một hình ảnh theo bối cảnh đơn giản. Chế độ cài đặt này sẽ ghi đè mọi cấu hình chung cho một phần cụ thể. Để biết chế độ cài đặt mặc định, hãy xem phần Số lượng mã thông báo.

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

Độ phân giải của nội dung đa phương tiện trên toàn cầu

Bạn có thể đặt độ phân giải mặc định cho tất cả các phần nội dung đa phương tiện trong một yêu cầu bằng cách sử dụng GenerationConfig. Tính năng này được hỗ trợ bởi tất cả các mô hình đa phương thức. Nếu một yêu cầu bao gồm cả chế độ cài đặt chung và chế độ cài đặt theo từng phần, thì chế độ cài đặt theo từng phần sẽ được ưu tiên cho mục cụ thể đó.

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"
    }
  }'

Các giá trị độ phân giải hợp lệ

Gemini API xác định các cấp độ sau cho độ phân giải của nội dung đa phương tiện:

• MEDIA_RESOLUTION_UNSPECIFIED: Chế độ cài đặt mặc định. Số lượng mã thông báo cho cấp độ này thay đổi đáng kể giữa Gemini 3 và các mô hình Gemini trước đó.
• MEDIA_RESOLUTION_LOW: Số lượng mã thông báo thấp hơn, giúp xử lý nhanh hơn và chi phí thấp hơn, nhưng ít chi tiết hơn.
• MEDIA_RESOLUTION_MEDIUM: Cân bằng giữa chi tiết, chi phí và độ trễ.
• MEDIA_RESOLUTION_HIGH: Số lượng mã thông báo cao hơn, cung cấp nhiều chi tiết hơn để mô hình hoạt động, nhưng đổi lại là độ trễ và chi phí tăng lên.
• MEDIA_RESOLUTION_ULTRA_HIGH (Chỉ theo từng phần): Số lượng mã thông báo cao nhất, cần thiết cho các trường hợp sử dụng cụ thể như sử dụng máy tính.

Xin lưu ý rằng MEDIA_RESOLUTION_HIGH mang lại hiệu suất tối ưu cho hầu hết các trường hợp sử dụng.

Số lượng mã thông báo chính xác được tạo cho từng cấp độ này phụ thuộc vào cả loại nội dung đa phương tiện (Hình ảnh, Video, PDF) và phiên bản mô hình.

Số lượng mã thông báo

Các bảng bên dưới tóm tắt số lượng mã thông báo gần đúng cho từng giá trị media_resolution và loại nội dung đa phương tiện theo họ mô hình.

Các mô hình Gemini 3

Các mô hình Gemini 2.5

Chọn độ phân giải phù hợp

• Mặc định (UNSPECIFIED): Bắt đầu với giá trị mặc định. Giá trị này được điều chỉnh để cân bằng tốt giữa chất lượng, độ trễ và chi phí cho hầu hết các trường hợp sử dụng phổ biến.
• LOW: Sử dụng cho các trường hợp mà chi phí và độ trễ là quan trọng nhất, còn chi tiết chi tiết thì ít quan trọng hơn.
• MEDIUM / HIGH: Tăng độ phân giải khi tác vụ yêu cầu hiểu các chi tiết phức tạp trong nội dung đa phương tiện. Điều này thường cần thiết cho việc phân tích hình ảnh phức tạp, đọc biểu đồ hoặc hiểu tài liệu dày đặc.
• ULTRA HIGH – Chỉ có sẵn cho chế độ cài đặt theo từng phần. Nên dùng cho các trường hợp sử dụng cụ thể như sử dụng máy tính hoặc khi thử nghiệm cho thấy có sự cải thiện rõ rệt so với HIGH.
• Kiểm soát theo từng phần (Gemini 3): Tối ưu hoá mức sử dụng mã thông báo. Ví dụ: trong một câu lệnh có nhiều hình ảnh, hãy sử dụng HIGH cho một sơ đồ phức tạp và LOW hoặc MEDIUM cho các hình ảnh theo bối cảnh đơn giản hơn.

Chế độ cài đặt được đề xuất

Sau đây là danh sách các chế độ cài đặt độ phân giải của nội dung đa phương tiện được đề xuất cho từng loại nội dung đa phương tiện được hỗ trợ.

Luôn kiểm thử và đánh giá tác động của các chế độ cài đặt độ phân giải khác nhau đối với ứng dụng cụ thể của bạn để tìm ra sự cân bằng tốt nhất giữa chất lượng, độ trễ và chi phí.

Tóm tắt khả năng tương thích với phiên bản

• Enum MediaResolution có sẵn cho tất cả các mô hình hỗ trợ dữ liệu đầu vào đa phương tiện.
• Số lượng mã thông báo được liên kết với từng cấp độ enum khác nhau giữa các mô hình Gemini 3 và các phiên bản Gemini trước đó.
• Việc đặt media_resolution trên từng đối tượng Part chỉ dành cho các mô hình Gemini 3.

Các bước tiếp theo

• Tìm hiểu thêm về các tính năng đa phương thức của Gemini API trong các hướng dẫn về hiểu hình ảnh, hiểu video và hiểu tài liệu.