미디어 해상도

미디어 해상도 (Media resolution)

media_resolution 파라미터는 Gemini API가 이미지, 비디오, 오디오, PDF 같은 미디어 입력을 처리하는 방식을 제어해요. 미디어 입력에 할당되는 최대 토큰 수를 결정해서, 응답 품질과 지연 시간·비용의 균형을 잡을 수 있게 해줘요.

출처: 원문

본문

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

요청 내 개별 미디어 객체(콘텐츠 항목)에 대해 미디어 해상도를 구성할 수도 있어요 (Gemini 3 전용).

콘텐츠 항목별 미디어 해상도 (Gemini 3 전용)

Gemini 3는 요청 내 개별 미디어 객체에 미디어 해상도를 설정할 수 있게 해서, 토큰 사용을 세밀하게 최적화할 수 있어요. 단일 요청에서 해상도 수준을 섞을 수 있어요. 예를 들어 복잡한 다이어그램에는 high 해상도, 단순한 컨텍스트 이미지에는 low 해상도를 쓰는 식이에요.

Python

from google import genai

client = genai.Client()

myfile = client.files.upload(file="path/to/image.jpg")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "text", "text": "Describe this image:"},
        {
            "type": "image",
            "uri": myfile.uri,
            "mime_type": myfile.mime_type,
            "resolution": "high"
        }
    ]
)
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/image.jpg",
    config: { mime_type: "image/jpeg" },
  });

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "text", text: "Describe this image:" },
      {
        type: "image",
        uri: myfile.uri,
        mime_type: myfile.mimeType,
        resolution: "high"
      }
    ],
  });
  console.log(interaction.output_text);
}

await main();

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.ImageContent;
import com.google.genai.gaos.models.interactions.ImageContentMimeType;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Describe the details in this high-resolution image.").build();
Content imageContent =
    ImageContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/image/scones.jpg")
        .mimeType(ImageContentMimeType.IMAGE_JPEG)
        .build();

List<Content> contents = Arrays.asList(textContent, imageContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    uploadedFile, err := client.Files.UploadFromPath(ctx, "path/to/image.jpg", nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput([]interactions.Content{
                interactions.NewContent(interactions.TextContent{
                    Text: "Describe the details in this high-resolution image.",
                }),
                interactions.NewContent(interactions.ImageContent{
                    URI:        genai.Ptr(uploadedFile.URI),
                    MimeType:   interactions.ImageContentMimeType(uploadedFile.MIMEType).ToPointer(),
                    Resolution: interactions.MediaResolutionHigh.ToPointer(),
                }),
            }),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

# First upload the file using the Files API, then use the URI:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: *** \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {"type": "text", "text": "Describe this image:"},
      {
        "type": "image",
        "uri": "YOUR_FILE_URI",
        "mime_type": "image/jpeg",
        "resolution": "high"
      }
    ]
  }'

사용 가능한 해상도 값

Gemini API는 미디어 해상도에 대해 다음 수준을 정의해요:

• unspecified: 기본 설정. 이 수준의 토큰 수는 Gemini 3와 이전 Gemini 모델 사이에서 크게 달라져요.
• low: 더 낮은 토큰 수로 처리 속도가 빠르고 비용이 낮지만, 디테일이 적어요.
• medium: 디테일, 비용, 지연 시간의 균형.
• high: 더 높은 토큰 수로 모델이 작업할 디테일이 많아지지만 지연 시간과 비용이 늘어나요.
• ultra_high (콘텐츠 항목별로만): 가장 높은 토큰 수. 컴퓨터 사용 같은 특정 사용 사례에 필요해요.

대부분의 사용 사례에서 high가 최적의 성능을 제공한다는 점을 참고하세요.

각 수준에서 생성되는 정확한 토큰 수는 미디어 유형(이미지, 비디오, 오디오, PDF)과 모델 버전에 따라 달라져요.

토큰 수

아래 표는 모델 계열별로 각 media_resolution 값과 미디어 유형의 대략적인 토큰 수를 요약해요.

Gemini 3 모델

올바른 해상도 고르기

• 기본값(unspecified): 기본값으로 시작하세요. 대부분의 일반적인 사용 사례에 품질·지연·비용의 좋은 균형으로 조정되어 있어요.
• low: 비용과 지연 시간이 가장 중요하고 세밀한 디테일이 덜 중요한 시나리오에 사용하세요.
• medium / high: 작업이 미디어 안의 복잡한 디테일 이해를 요구할 때 해상도를 높이세요. 복잡한 시각 분석, 차트 읽기, 밀도 높은 문서 이해에 자주 필요해요.
• ultra_high: 콘텐츠 항목별 설정에서만 사용 가능해요. 컴퓨터 사용이나 테스트에서 high보다 명확한 개선이 확인된 특정 사용 사례에 권장돼요.
• 콘텐츠 항목별 제어 (Gemini 3): 토큰 사용을 최적화해요. 예를 들어 여러 이미지가 있는 프롬프트에서 복잡한 다이어그램에는 high, 단순한 컨텍스트 이미지에는 low나 medium을 사용하세요.

권장 설정

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

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

비디오 처리 모드와의 관계

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

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

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

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

버전 호환성 요약

• 개별 콘텐츠 항목에 resolution을 설정하는 것은 Gemini 3 모델 전용 기능이에요.

다음 단계

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

더 알아보기 (Learn more)

• 이미지 이해
• 비디오 이해
• 문서 처리