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. Isso permite equilibrar a qualidade da resposta com a latência e o custo. Enquanto as entradas visuais e de documentos dimensionam 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 conferir diferentes configurações, valores padrão e como eles correspondem a tokens, consulte a seção Contagem de tokens.

É possível configurar a resolução de mídia para objetos de mídia individuais (itens de conteúdo) na sua solicitação (somente Gemini 3).

Resolução de mídia por item de conteúdo (somente Gemini 3)

Com o Gemini 3, é possível definir a resolução de mídia para objetos individuais na sua 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, use alta resolução para um diagrama complexo e baixa resolução para uma imagem contextual simples.

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)

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();

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(""));

# 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: $GEMINI_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"
      }
    ]
  }'

Valores de resolução disponíveis

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

• unspecified: a configuração padrão. A contagem de tokens para esse nível varia muito entre o Gemini 3 e os modelos anteriores.
• low: contagem de tokens menor, resultando em processamento mais rápido e custo menor, mas com menos detalhes.
• medium: um equilíbrio entre detalhes, custo e latência.
• high: contagem de tokens mais alta, fornecendo mais detalhes para o modelo trabalhar, mas com aumento da latência e do custo.
• ultra_high (apenas por item de conteúdo): contagem máxima de tokens, necessária para casos de uso específicos, como uso de computador.

O 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.

Contagem de tokens

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

Modelos do Gemini 3

Como escolher a resolução certa

• Padrão (unspecified): comece com o padrão. Ele é ajustado para um bom equilíbrio entre qualidade, latência e custo nos casos de uso mais comuns.
• low:use em cenários em que o custo e a latência são fundamentais, e o detalhe refinado é menos importante.
• 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 a configuração por item de conteúdo. Recomendado para casos de uso específicos, como uso de computador ou quando o teste mostra uma melhoria clara em relação a high.
• Controle por item de conteúdo (Gemini 3): otimiza o uso de tokens. Por exemplo, em um comando com várias imagens, use high para um diagrama complexo e low ou medium para imagens contextuais mais simples.

Configurações recomendadas

Confira abaixo 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 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 com agentes com baixa resolução de mídia para minimizar o uso total de tokens em um vídeo longo.

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

Resumo da compatibilidade de versões

• A definição do resolution em itens de conteúdo individuais é exclusiva dos modelos do Gemini 3.

Próximas etapas

• Saiba mais sobre os recursos multimodais da API Gemini nos guias de compreensão de imagens, entendimento de vídeo, compreensão de áudio e compreensão de documentos.