Resolución de medios

El parámetro media_resolution controla cómo la API de Gemini procesa las entradas de medios, como imágenes, videos y documentos PDF, ya que determina la cantidad máxima de tokens asignados para las entradas de medios, lo que te permite equilibrar la calidad de la respuesta con la latencia y el costo. Para conocer los diferentes parámetros de configuración, los valores predeterminados y cómo se corresponden con los tokens, consulta la sección Recuento de tokens.

Puedes configurar la resolución de medios de dos maneras:

• Por parte (solo Gemini 3)

• De forma global para una solicitud generateContent completa (todos los modelos multimodales)

Resolución de medios por parte (solo Gemini 3)

Gemini 3 te permite establecer la resolución de medios para objetos de medios individuales dentro de tu solicitud, lo que ofrece una optimización detallada del uso de tokens. Puedes combinar niveles de resolución en una sola solicitud. Por ejemplo, usar alta resolución para un diagrama complejo y baja resolución para una imagen contextual simple. Este parámetro de configuración anula cualquier configuración global para una parte específica. Para conocer la configuración predeterminada, consulta la sección Recuento de tokens.

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.1-pro-preview'

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: '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.1-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();

# 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.1-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

Resolución de medios global

Puedes establecer una resolución predeterminada para todas las partes de medios en una solicitud con GenerationConfig. Esto es compatible con todos los modelos multimodales. Si una solicitud incluye parámetros de configuración globales y por parte, el parámetro de configuración por parte tiene prioridad para ese elemento 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-flash-preview',
    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-flash-preview',
      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-flash-preview: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 resolución disponibles

La API de Gemini define los siguientes niveles para la resolución de medios:

• MEDIA_RESOLUTION_UNSPECIFIED: Es la configuración predeterminada. El recuento de tokens para este nivel varía significativamente entre Gemini 3 y los modelos de Gemini anteriores.
• MEDIA_RESOLUTION_LOW: Recuento de tokens más bajo, lo que genera un procesamiento más rápido y un costo menor, pero con menos detalles.
• MEDIA_RESOLUTION_MEDIUM: Un equilibrio entre detalles, costo y latencia.
• MEDIA_RESOLUTION_HIGH: Recuento de tokens más alto, que proporciona más detalles para que el modelo funcione, a costa de aumentar la latencia y el costo.
• MEDIA_RESOLUTION_ULTRA_HIGH (solo por parte): Recuento de tokens más alto, necesario para casos de uso específicos, como el uso de computadoras.

Ten en cuenta que MEDIA_RESOLUTION_HIGH proporciona el rendimiento óptimo para la mayoría de los casos de uso.

La cantidad exacta de tokens generados para cada uno de estos niveles depende del tipo de medio (imagen, video, PDF) y de la versión del modelo.

Recuento de tokens

En las siguientes tablas, se resumen los recuentos de tokens aproximados para cada valor media_resolution y tipo de medio por familia de modelos.

Modelos de Gemini 3

Modelos de Gemini 2.5

Cómo elegir la resolución correcta

• Predeterminado (UNSPECIFIED): Comienza con el valor predeterminado. Está optimizado para un buen equilibrio entre calidad, latencia y costo para los casos de uso más comunes.
• LOW: Úsalo en situaciones en las que el costo y la latencia son fundamentales, y los detalles precisos son menos importantes.
• MEDIUM / HIGH: Aumenta la resolución cuando la tarea requiere comprender detalles complejos dentro de los medios. Esto suele ser necesario para el análisis visual complejo, la lectura de gráficos o la comprensión de documentos densos.
• ULTRA HIGH : Solo está disponible para la configuración por parte. Se recomienda para casos de uso específicos, como el uso de computadoras o cuando las pruebas muestran una mejora clara en comparación con HIGH.
• Control por parte (Gemini 3): Optimiza el uso de tokens. Por ejemplo, en una instrucción con varias imágenes, usa HIGH para un diagrama complejo y LOW o MEDIUM para imágenes contextuales más simples.

Configuración recomendada

A continuación, se enumeran los parámetros de configuración de resolución de medios recomendados para cada tipo de medio compatible.

Siempre prueba y evalúa el impacto de diferentes parámetros de configuración de resolución en tu aplicación específica para encontrar el mejor equilibrio entre calidad, latencia y costo.

Resumen de compatibilidad de versiones

• La enumeración MediaResolution está disponible para todos los modelos que admiten entrada de medios.
• Los recuentos de tokens asociados con cada nivel de enumeración difieren entre los modelos de Gemini 3 y las versiones anteriores de Gemini.
• Establecer media_resolution en objetos Part individuales es exclusivo de los modelos de Gemini 3.

Próximos pasos

• Obtén más información sobre las capacidades multimodales de la API de Gemini en las guías de comprensión de imágenes, comprensión de videos y comprensión de documentos.