Resolução da mídia

O parâmetro media_resolution controla como a API Gemini processa entradas de mídia, como imagens, vídeos, áudio e documentos PDF, determinando o número máximo de tokens alocados para entradas de mídia, permitindo equilibrar a qualidade da resposta com a latência e o custo. Enquanto as entradas visuais e de documentos escalonam a alocação de tokens com base na configuração de resolução, as entradas de áudio são tokenizadas a uma taxa fixa por segundo em todos os níveis de resolução. Para diferentes configurações, valores padrão e como eles correspondem a tokens, consulte a seção Contagens de tokens.

É possível configurar a resolução de mídia de duas maneiras:

• Por parte (modelos Gemini 4 e Gemini 3)

• Globalmente para uma solicitação generateContent inteira (todos os modelos multimodais)

Resolução de mídia por parte (Gemini 4 e Gemini 3)

O Gemini 4 e o Gemini 3 permitem definir a resolução de mídia para objetos de mídia individuais na solicitação, oferecendo uma otimização refinada do uso de tokens. É possível misturar níveis de resolução em uma única solicitação. Por exemplo, usando alta resolução para um diagrama complexo e baixa resolução para uma imagem contextual. Essa configuração substitui qualquer configuração global para uma parte específica. Para configurações padrão, consulte a seção Contagens de tokens.

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

Resolução de mídia global

É possível definir uma resolução padrão para todos os trechos de áudio em uma solicitação usando a GenerationConfig. Isso é compatível com todos os modelos multimodais. Se uma solicitação incluir configurações globais e por parte, a configuração por parte terá precedência para esse item específico.

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

Valores de resolução disponíveis

A API Gemini define os seguintes níveis de resolução de mídia:

• MEDIA_RESOLUTION_UNSPECIFIED: a configuração padrão. A contagem de tokens para esse nível varia significativamente entre o Gemini 3 e modelos anteriores do Gemini.
• MEDIA_RESOLUTION_LOW: contagem de tokens mais baixa, resultando em processamento mais rápido e custo menor, mas com menos detalhes.
• MEDIA_RESOLUTION_MEDIUM: um equilíbrio entre detalhes, custo e latência.
• MEDIA_RESOLUTION_HIGH: contagem de tokens mais alta, fornecendo mais detalhes para o modelo trabalhar, à custa de maior latência e custo.
• MEDIA_RESOLUTION_ULTRA_HIGH (somente por parte): contagem de tokens mais alta, necessária para casos de uso específicos, como uso de computador.

A MEDIA_RESOLUTION_HIGH oferece a performance ideal para a maioria dos casos de uso.

O número exato de tokens gerados para cada um desses níveis depende do tipo de mídia (imagem, vídeo, áudio, PDF) e da versão do modelo.

Contagens de tokens

As tabelas abaixo resumem as contagens de tokens aproximadas para cada valor media_resolution e tipo de mídia por família de modelos.

Modelos do Gemini 3

Modelos do Gemini 2.5

Como escolher a resolução certa

• Padrão (UNSPECIFIED) : comece com o padrão. Ele é ajustado para um bom equilíbrio de qualidade, latência e custo para a maioria dos casos de uso comuns.
• LOW:use para cenários em que o custo e a latência são fundamentais e detalhes refinados são menos importantes.
• MEDIUM / HIGH:aumente a resolução quando a tarefa exigir a compreensão de detalhes complexos na mídia. Isso geralmente é necessário para análises visuais complexas, leitura de gráficos ou compreensão de documentos densos.
• ULTRA HIGH : disponível apenas para configuração por parte. Recomendado para casos de uso específicos, como uso de computador ou quando os testes mostram uma melhoria clara em relação a HIGH.
• Controle por parte (Gemini 4 e Gemini 3) : otimiza o uso de tokens. Por exemplo, em um prompt com várias imagens, use HIGH para um diagrama complexo e LOW ou MEDIUM para imagens contextuais mais simples.

Configurações recomendadas

A lista a seguir mostra as configurações de resolução de mídia recomendadas para cada tipo de mídia compatível.

Sempre teste e avalie o impacto de diferentes configurações de resolução no seu aplicativo específico para encontrar o melhor equilíbrio entre qualidade, latência e custo.

Relação com os modos de processamento de vídeo

Os parâmetros media_resolution e de processamento controlam diferentes aspectos da entrada de vídeo:

• media_resolution controla a resolução de cada frame (número de tokens por frame).
• processing / media_processing controla qual conteúdo do vídeo é carregado no contexto.

É possível definir os dois na mesma entrada de vídeo. Por exemplo, você pode usar o processamento de agente com baixa resolução de mídia para minimizar o uso total de tokens em um vídeo longo.

Para mais detalhes sobre os modos de processamento de vídeo, consulte o guia Entendimento de vídeo de agente.

Resumo da compatibilidade de versões

• A enumeração MediaResolution está disponível para todos os modelos que oferecem suporte à entrada de mídia.
• As contagens de tokens associadas a cada nível de enumeração são diferentes entre os modelos do Gemini 4 / Gemini 3 e versões anteriores do Gemini.
• A configuração media_resolution em objetos Part individuais é compatível com os modelos do Gemini 4 e do Gemini 3.

Próximas etapas

• Saiba mais sobre os recursos multimodais da API Gemini nos guias Entendimento de imagens, Entendimento de vídeos, Entendimento de áudio e Entendimento de documentos.