Resolución de contenido multimedia

El parámetro media_resolution controla cómo la API de Gemini procesa las entradas de medios, como imágenes, videos, audio 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. Si bien las entradas visuales y de documentos escalan la asignación de tokens según la configuración de resolución, las entradas de audio se tokenizan a una tasa fija por segundo en todos los niveles de resolución. Para conocer los diferentes parámetros de configuración, los valores predeterminados y cómo se corresponden con los tokens, consulta la sección Recuentos de tokens.

Puedes configurar la resolución de medios para objetos de medios individuales (elementos de contenido) dentro de tu solicitud (modelos de Gemini 4 y Gemini 3).

Resolución de medios por elemento de contenido (modelos de Gemini 4 y Gemini 3)

Los modelos de Gemini 4 y Gemini 3 te permiten 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, puedes usar alta resolución para un diagrama complejo y baja resolución para una imagen contextual simple.

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

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)
    }
}

# 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 resolución disponibles

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

• unspecified: Es la configuración predeterminada. El recuento de tokens para este nivel varía significativamente entre Gemini 4/3 y los modelos de Gemini anteriores.
• low: Recuento de tokens más bajo, lo que genera un procesamiento más rápido y un costo menor, pero con menos detalles.
• medium: Un equilibrio entre detalles, costo y latencia.
• high: Recuento de tokens más alto, que proporciona más detalles para que el modelo funcione, a costa de una mayor latencia y costo.
• ultra_high (solo por elemento de contenido): Recuento de tokens más alto, necesario para casos de uso específicos, como el uso de computadoras.

Ten en cuenta que 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 tanto del tipo de medio (imagen, video, audio, PDF) como de la versión del modelo.

Recuentos de tokens

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

Modelos de Gemini 4 y Gemini 3

Cómo elegir la resolución correcta

• Predeterminado (unspecified): Comienza con el valor predeterminado. Está optimizado para lograr un buen equilibrio entre calidad, latencia y costo para la mayoría de los casos de uso 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 elemento de contenido. 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 elemento de contenido (Gemini 4 y Gemini 3): Optimiza el uso de tokens. Por ejemplo, en un prompt 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 los diferentes parámetros de configuración de resolución en tu aplicación para encontrar el mejor equilibrio entre calidad, latencia y costo.

Relación con los modos de procesamiento de video

Los parámetros media_resolution y de procesamiento controlan diferentes aspectos de la entrada de video:

• media_resolution controla la resolución de cada fotograma (cantidad de tokens por fotograma).
• processing / media_processing controla qué contenido del video se carga en el contexto.

Puedes configurar ambos en la misma entrada de video. Por ejemplo, puedes usar el procesamiento de agentes con baja resolución de medios para minimizar el uso total de tokens para un video largo.

Para obtener detalles sobre los modos de procesamiento de video, consulta la guía Comprensión de videos de agentes.

Resumen de compatibilidad de versiones

• La configuración de resolution en elementos de contenido individuales es compatible con los modelos de Gemini 4 y Gemini 3.

Próximos pasos

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