미디어 해상도

미디어 해상도 (generateContent)

media_resolution 파라미터는 Gemini API가 이미지, 비디오, 오디오, PDF 같은 미디어 입력에 할당하는 최대 토큰 수를 결정해요. 전체 generateContent 요청에 글로벌로 설정하거나, Gemini 3에서는 개별 파트에 설정할 수 있어요.

출처: 원문

본문

media_resolution 파라미터는 미디어 입력에 할당되는 최대 토큰 수를 결정해서, 응답 품질과 지연 시간·비용의 균형을 잡을 수 있게 해줘요. 시각·문서 입력은 해상도 설정에 따라 토큰 할당을 확장하지만, 오디오 입력은 모든 해상도 수준에서 초당 고정 비율로 토큰화돼요.

미디어 해상도는 두 가지 방식으로 구성할 수 있어요:

• 파트별 (Gemini 3 전용)
• 전체 generateContent 요청에 글로벌 (모든 멀티모달 모델)

파트별 미디어 해상도 (Gemini 3 전용)

Gemini 3는 요청 내 개별 미디어 객체의 미디어 해상도를 설정해 토큰 사용을 세밀하게 최적화할 수 있게 해줘요. 단일 요청에서 해상도 수준을 섞을 수 있어요. 예를 들어 복잡한 다이어그램에는 high, 컨텍스트 이미지에는 low를 쓰는 식이에요. 이 설정은 특정 파트에 대한 글로벌 구성을 덮어써요. 기본 설정은 토큰 수 섹션을 참고하세요.

참고: 파트별 미디어 해상도는 실험 기능이에요.

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: *** \
  -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.8-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.8-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.8-flash:generateContent" \
  -H "x-goog-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 3): 토큰 사용을 최적화해요. 예를 들어 여러 이미지가 있는 프롬프트에서 복잡한 다이어그램에는 HIGH, 단순한 컨텍스트 이미지에는 LOW나 MEDIUM을 사용하세요.

권장 설정

지원되는 각 미디어 유형에 권장되는 미디어 해상도 설정을 정리하면 다음과 같아요.

항상 다양한 해상도 설정이 특정 애플리케이션에 미치는 영향을 테스트하고 평가해서 품질·지연·비용 간 최상의 트레이드오프를 찾아보세요.

비디오 처리 모드와의 관계

media_resolution과 처리 파라미터는 비디오 입력의 서로 다른 측면을 제어해요:

• media_resolution은 각 프레임의 해상도(프레임당 토큰 수)를 제어해요.
• processing / media_processing은 비디오의 어느 콘텐츠가 컨텍스트에 로드되는지 제어해요.

둘 다 같은 비디오 입력에 설정할 수 있어요. 예를 들어 긴 비디오의 총 토큰 사용을 최소화하려면 낮은 미디어 해상도와 에이전트 처리(agentic processing)를 함께 쓸 수 있어요.

비디오 처리 모드에 대한 자세한 내용은 Agentic video understanding 가이드를 참고하세요.

버전 호환성 요약

• MediaResolution 열거형은 미디어 입력을 지원하는 모든 모델에서 사용할 수 있어요.
• 각 열거형 수준과 관련된 토큰 수는 Gemini 3 모델과 이전 Gemini 버전 사이에서 다릅니다.
• 개별 Part 객체에 media_resolution을 설정하는 것은 Gemini 3 모델 전용 기능이에요.

다음 단계

• Gemini API의 멀티모달 기능에 대해 더 알아보려면 이미지 이해, 비디오 이해, 오디오 이해, 문서 이해 가이드를 참고하세요.

더 알아보기 (Learn more)

• 미디어 해상도
• 이미지 이해
• 비디오 이해