> ## AI Agent Context
> Get the complete documentation index at: https://aistudio.google.com/llms.txt
> Use this file to discover all available pages.
> For the full documentation in a single file, fetch: https://aistudio.google.com/llms-full.txt

# Media resolution

The `media_resolution` parameter controls how the Gemini API processes media
inputs like images, videos, audio, and PDF documents by determining the
**maximum number of tokens** allocated for media inputs, allowing you to
balance response quality against latency and cost. While visual and document
inputs scale token allocation based on the resolution setting, audio inputs
are tokenized at a fixed rate per second across all resolution levels. For
different settings, default values and how they correspond to tokens, see the
[Token counts](/docs/media-resolution#token-counts) section.

You can configure media resolution for individual media objects (content items)
within your request (Gemini 4 and Gemini 3 models).

## Per-content-item media resolution (Gemini 4 and Gemini 3 models)  {% id="per-content-item-media-resolution" %}

Gemini 4 and Gemini 3 models allow you to set media resolution for individual media objects within
your request, offering fine-grained optimisation of token usage. You can mix
resolution levels in a single request. For example, using high resolution for a
complex diagram and low resolution for a simple contextual image.

{% tabs %}
  {% tab label="Python" %}
  ```python
  from google import genai
  
  client = genai.Client()
  
  myfile = client.files.upload(file="path/to/image.jpg")
  
  interaction = client.interactions.create(
      model="gemini-4-hydrogen",
      input=[
          {"type": "text", "text": "Describe this image:"},
          {
              "type": "image",
              "uri": myfile.uri,
              "mime_type": myfile.mime_type,
              "resolution": "high"
          }
      ]
  )
  print(interaction.output_text)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
  import { GoogleGenAI } from "@google/genai";
  
  const ai = new GoogleGenAI({});
  
  async function main() {
    const myfile = await ai.files.upload({
      file: "path/to/image.jpg",
      config: { mimeType: "image/jpeg" },
    });
  
    const interaction = await ai.interactions.create({
      model: "gemini-4-hydrogen",
      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();
  ```

  {% /tab %}

  {% tab label="Java" %}
  ```java
  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-4-hydrogen"))
          .input(InteractionsInput.ofContent(contents))
          .build();
  
  Interaction interaction =
      client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();
  
  System.out.println(interaction.outputText().orElse(""));
  ```

  {% /tab %}

  {% tab label="Go" %}
  ```go
  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-4-hydrogen"),
              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)
      }
  }
  ```

  {% /tab %}

  {% tab label="REST" %}
  ```shell
  # 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' \
    -H "Api-Revision: 2026-05-20" \
    -d '{
      "model": "gemini-4-hydrogen",
      "input": [
        {"type": "text", "text": "Describe this image:"},
        {
          "type": "image",
          "uri": "YOUR_FILE_URI",
          "mime_type": "image/jpeg",
          "resolution": "high"
        }
      ]
    }'
  ```

  {% /tab %}

{% /tabs %}

## Available resolution values  {% id="available-resolution-values" %}

The Gemini API defines the following levels for media resolution:

* `unspecified`: The default setting. The token count for this level varies significantly between Gemini 4/3 and earlier Gemini models.
* `low`: Lower token count, resulting in faster processing and lower cost, but with less detail.
* `medium`: A balance between detail, cost, and latency.
* `high`: Higher token count, providing more detail for the model to work with, at the expense of increased latency and cost.
* `ultra_high` (Per content item only): Highest token count, required for specific use cases such as [computer use](/docs/computer-use).

Note that `high` provides the optimal performance for most use cases.

The exact number of tokens generated for each of these levels depends on both
the **media type** (Image, Video, Audio, PDF) and the **model version**.

## Token counts  {% id="token-counts" %}

The tables below summarize the approximate token counts for each
`media_resolution` value and media type per model family.

**Gemini 4 and Gemini 3 models**

| MediaResolution | Image | Video | Audio | PDF |
| :--- | :--- | :--- | :--- | :--- |
| `unspecified` (Default) | 1120 | 70 | 25 (per second) | 560 |
| `low` | 280 | 70 | 25 (per second) | 280 + Native Text |
| `medium` | 560 | 70 | 25 (per second) | 560 + Native Text |
| `high` | 1120 | 280 | 25 (per second) | 1120 + Native Text |
| `ultra_high` | 2240 | N/A | N/A | N/A |

## Choosing the right resolution  {% id="choosing-the-right-resolution" %}

* **Default (`unspecified`):** Start with the default. It's tuned for a good balance of quality, latency, and cost for most common use cases.
* **`low`:** Use for scenarios where cost and latency are paramount, and fine-grained detail is less critical.
* **`medium` / `high`:** Increase the resolution when the task requires
  understanding intricate details within the media. This is often needed for
  complex visual analysis, chart reading, or dense document comprehension.
* **`ultra_high`** - Only available for per content item setting. Recommended
  for specific use cases such as computer use or where testing shows a clear
  enhancement over `high`.
* **Per-content-item control (Gemini 4 and Gemini 3):** Optimizes token usage. For example,
  in a prompt with multiple images, use `high` for a complex diagram and `low`
  or `medium` for simpler contextual images.

**Recommended settings**

The following lists the recommended media resolution settings for each supported
media type.

| Media Type | Recommended Setting | Max Tokens | Usage Guidance |
| :--- | :--- | :--- | :--- |
| **Images** | `high` | 1120 | Recommended for most image analysis tasks to ensure maximum quality. |
| **PDFs** | `medium` | 560 | Optimal for document understanding; quality typically saturates at `medium`. Increasing to `high` rarely improves OCR results for standard documents. |
| **Video** (General) | `low` (or `medium`) | 70 (per frame) | **Note:** For video, `low` and `medium` settings are treated identically (70 tokens) to optimize context usage. This is sufficient for most action recognition and description tasks. |
| **Video** (Text-heavy) | `high` | 280 (per frame) | Required only when the use case involves reading dense text (OCR) or small details within video frames. |
| **Audio** | `unspecified` (Default) | 25 (per second) | Audio is tokenized at a fixed rate of 25 tokens per second across all supported resolution settings (`unspecified`, `low`, `medium`, and `high`). |

Always test and evaluate the impact of different resolution settings on your
application to find the best trade-off between quality, latency, and cost.

## Relationship with video processing modes  {% id="relationship-with-video-processing-modes" %}

For video content, `media_resolution` controls the token budget per frame, while
the `processing` mode controls *which* content from the video is loaded. These two settings
operate independently: you can use low, medium, or high resolution with either
static processing or agentic video understanding. For details, see
[Agentic video understanding](/docs/video-understanding#agentic-video-understanding).

## Version compatibility summary  {% id="version-compatibility-summary" %}

* Setting the `resolution` on individual content items is **supported on Gemini 4 and Gemini 3 models**.

## Next steps  {% id="next-steps" %}

* Learn more about the multimodal capabilities of Gemini API in the
  [image understanding](/docs/image-understanding),
  [video understanding](/docs/video-understanding),
  [audio understanding](/docs/audio), and
  [document understanding](/docs/document-processing) guides.

