미디어 해상도

media_resolution 매개변수는 이미지, 동영상, PDF 문서와 같은 미디어 입력이 Gemini API에서 처리되는 방식을 제어합니다. 미디어 입력에 할당된 최대 토큰 수를 결정하여 지연 시간 및 비용에 대한 응답 품질의 균형을 맞출 수 있습니다. 다양한 설정, 기본값, 토큰과의 상응 관계는 토큰 수 섹션을 참고하세요.

미디어 해상도는 다음 두 가지 방법으로 구성할 수 있습니다.

  • 파트별 (Gemini 3만 해당)

  • 전체 generateContent 요청 (모든 멀티모달 모델)에 대해 전역

부분별 미디어 해상도 (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 이미지 동영상 PDF
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 (프레임당) 참고: 동영상의 경우 컨텍스트 사용을 최적화하기 위해 lowmedium 설정이 동일하게 처리됩니다 (70개 토큰). 대부분의 동작 인식 및 설명 작업에는 이 정도면 충분합니다.
동영상 (텍스트 중심) MEDIA_RESOLUTION_HIGH 280 (프레임당) 사용 사례에 밀도 높은 텍스트 (OCR) 또는 동영상 프레임 내의 작은 세부정보를 읽는 작업이 포함된 경우에만 필요합니다.

항상 다양한 해상도 설정이 특정 애플리케이션에 미치는 영향을 테스트하고 평가하여 품질, 지연 시간, 비용 간의 최적의 절충점을 찾으세요.

버전 호환성 요약

  • MediaResolution enum은 미디어 입력을 지원하는 모든 모델에서 사용할 수 있습니다.
  • 각 enum 수준과 연결된 토큰 수는 Gemini 3 모델과 이전 Gemini 버전 간에 다릅니다.
  • 개별 Part 객체에 media_resolution를 설정하는 것은 Gemini 3 모델에만 해당됩니다.

다음 단계