O parâmetro media_resolution controla como a API Gemini processa entradas de mídia, como imagens, vídeos e documentos PDF, determinando o número máximo de tokens alocados para entradas de mídia. Assim, é possível equilibrar a qualidade da resposta com a latência e o custo. 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 da mídia de duas maneiras:
Por parte (somente Gemini 3)
Globalmente para uma solicitação
generateContentinteira (todos os modelos multimodais)
Resolução de mídia por parte (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. Essa configuração substitui qualquer configuração global de uma peça específica. Para conferir as configurações padrão, consulte a seção Contagem de tokens.
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
Resolução de mídia global
É possível definir uma resolução padrão para todas as partes de mídia em uma solicitação usando o
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.
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"
}
}'
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 muito entre o Gemini 3 e os modelos anteriores do Gemini.MEDIA_RESOLUTION_LOW: menor contagem de tokens, 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: maior contagem de tokens, fornecendo mais detalhes para o modelo trabalhar, mas com aumento da latência e do custo.- (Em breve)
MEDIA_RESOLUTION_ULTRA_HIGH: contagem máxima de tokens necessária para casos de uso específicos, como uso de computador.
O número exato de tokens gerados para cada um desses níveis depende do tipo de mídia (imagem, vídeo, 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
| MediaResolution | Imagem | Vídeo | |
MEDIA_RESOLUTION_UNSPECIFIED (padrão)
|
1120 | 70 | 560 |
MEDIA_RESOLUTION_LOW
|
280 | 70 | 280 + texto nativo |
MEDIA_RESOLUTION_MEDIUM
|
560 | 70 | 560 + texto nativo |
MEDIA_RESOLUTION_HIGH
|
1120 | 280 | 1120 + texto nativo |
Modelos do Gemini 2.5
| MediaResolution | Imagem | Vídeo | PDF (digitalizado) | PDF (nativo) |
MEDIA_RESOLUTION_UNSPECIFIED (padrão)
|
256 + Pan & Scan (~2048) | 256 | 256 + OCR | 256 + texto nativo |
MEDIA_RESOLUTION_LOW
|
64 | 64 | 64 + OCR | 64 + texto nativo |
MEDIA_RESOLUTION_MEDIUM
|
256 | 256 | 256 + OCR | 256 + texto nativo |
MEDIA_RESOLUTION_HIGH
|
256 + Pan & Scan | 256 | 256 + OCR | 256 + texto nativo |
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 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.- Controle por parte (Gemini 3): use isso para otimizar o uso de tokens. Por exemplo, em um comando com várias imagens, use
HIGHpara um diagrama complexo eLOWouMEDIUMpara 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.
| Tipo de mídia | Configuração recomendada | Máximo de tokens | Orientações de uso |
| Imagens | MEDIA_RESOLUTION_HIGH
|
1120 | Recomendado para a maioria das tarefas de análise de imagens para garantir a qualidade máxima. |
| PDFs | MEDIA_RESOLUTION_MEDIUM
|
560 | Ideal para compreensão de documentos. A qualidade geralmente satura em medium. Aumentar para high raramente melhora os resultados do OCR em documentos padrão.
|
| Vídeo (Geral) | MEDIA_RESOLUTION_LOW (ou MEDIA_RESOLUTION_MEDIUM)
|
70 (por frame) | Observação:para vídeo, as configurações low e medium são tratadas de forma idêntica (70 tokens) para otimizar o uso do contexto. Isso é suficiente para a maioria das tarefas de reconhecimento e descrição de ações.
|
| Vídeo (com muito texto) | MEDIA_RESOLUTION_HIGH
|
280 (por frame) | Obrigatório apenas quando o caso de uso envolve a leitura de texto denso (OCR) ou pequenos detalhes em frames de vídeo. |
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.
Resumo da compatibilidade de versões
- O tipo enumerado
MediaResolutionestá disponível para todos os modelos que aceitam entrada de mídia. - As contagens de tokens associadas a cada nível de enumeração são diferentes entre os modelos do Gemini 3 e as versões anteriores do Gemini.
- A definição de
media_resolutionem objetosPartindividuais é 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, compreensão de vídeos e compreensão de documentos.