Repository Public
1The `media_resolution` parameter controls how the Gemini API processes media2inputs like images, videos, audio, and PDF documents by determining the3**maximum number of tokens** allocated for media inputs, allowing you to4balance response quality against latency and cost. While visual and document5inputs scale token allocation based on the resolution setting, audio inputs6are tokenized at a fixed rate per second across all resolution levels. For7different settings, default values and how they correspond to tokens, see the8[Token counts](https://ai.google.dev/gemini-api/docs/media-resolution#token-counts) section.910You can configure media resolution for individual media objects (content items) within your request (Gemini 3 only).1112## Per-content-item media resolution (Gemini 3 only)1314Gemini 3 allows 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.1516### Python1718 from google import genai1920 client = genai.Client()2122 myfile = client.files.upload(file="path/to/image.jpg")2324 interaction = client.interactions.create(25 model="gemini-3.8-flash",26 input=[27 {"type": "text", "text": "Describe this image:"},28 {29 "type": "image",30 "uri": myfile.uri,31 "mime_type": myfile.mime_type,32 "resolution": "high"33 }34 ]35 )36 print(interaction.output_text)3738### JavaScript3940 import { GoogleGenAI } from "@google/genai";4142 const ai = new GoogleGenAI({});4344 async function main() {45 const myfile = await ai.files.upload({46 file: "path/to/image.jpg",47 config: { mime_type: "image/jpeg" },48 });4950 const interaction = await ai.interactions.create({51 model: "gemini-3.8-flash",52 input: [53 { type: "text", text: "Describe this image:" },54 {55 type: "image",56 uri: myfile.uri,57 mime_type: myfile.mimeType,58 resolution: "high"59 }60 ],61 });62 console.log(interaction.output_text);63 }6465 await main();6667### Java6869 import com.google.genai.Client;70 import com.google.genai.gaos.models.interactions.Content;71 import com.google.genai.gaos.models.interactions.CreateModelInteraction;72 import com.google.genai.gaos.models.interactions.ImageContent;73 import com.google.genai.gaos.models.interactions.ImageContentMimeType;74 import com.google.genai.gaos.models.interactions.Interaction;75 import com.google.genai.gaos.models.interactions.InteractionsInput;76 import com.google.genai.gaos.models.interactions.Model;77 import com.google.genai.gaos.models.interactions.TextContent;78 import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;79 import java.util.Arrays;80 import java.util.List;8182 Client client = new Client();8384 Content textContent = TextContent.builder().text("Describe the details in this high-resolution image.").build();85 Content imageContent =86 ImageContent.builder()87 .uri("gs://cloud-samples-data/generative-ai/image/scones.jpg")88 .mimeType(ImageContentMimeType.IMAGE_JPEG)89 .build();9091 List<Content> contents = Arrays.asList(textContent, imageContent);9293 CreateModelInteraction params =94 CreateModelInteraction.builder()95 .model(Model.of("gemini-3.8-flash"))96 .input(InteractionsInput.ofContent(contents))97 .build();9899 Interaction interaction =100 client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();101102 System.out.println(interaction.outputText().orElse(""));103104### REST105106 # First upload the file using the Files API, then use the URI:107 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \108 -H "x-goog-api-key: $GEMINI_API_KEY" \109 -H 'Content-Type: application/json' \110 -d '{111 "model": "gemini-3.8-flash",112 "input": [113 {"type": "text", "text": "Describe this image:"},114 {115 "type": "image",116 "uri": "YOUR_FILE_URI",117 "mime_type": "image/jpeg",118 "resolution": "high"119 }120 ]121 }'122123## Available resolution values124125The Gemini API defines the following levels for media resolution:126127- `unspecified`: The default setting. The token count for this level varies significantly between Gemini 3 and earlier Gemini models.128- `low`: Lower token count, resulting in faster processing and lower cost, but with less detail.129- `medium`: A balance between detail, cost, and latency.130- `high`: Higher token count, providing more detail for the model to work with, at the expense of increased latency and cost.131- `ultra_high` (Per content item only): Highest token count, required for specific use cases such as [computer use](https://ai.google.dev/gemini-api/docs/computer-use).132133Note that `high` provides the optimal performance for most use cases.134135The exact number of tokens generated for each of these levels depends on both136the **media type** (Image, Video, Audio, PDF) and the **model version**.137138## Token counts139140The tables below summarize the approximate token counts for each `media_resolution` value and media type per model family.141142**Gemini 3 models**143144| MediaResolution | Image | Video | Audio | PDF |145|---|---|---|---|---|146| `unspecified` (Default) | 1120 | 70 | 25 (per second) | 560 |147| `low` | 280 | 70 | 25 (per second) | 280 + Native Text |148| `medium` | 560 | 70 | 25 (per second) | 560 + Native Text |149| `high` | 1120 | 280 | 25 (per second) | 1120 + Native Text |150| `ultra_high` | 2240 | N/A | N/A | N/A |151152## Choosing the right resolution153154- **Default (`unspecified`):** Start with the default. It's tuned for a good balance of quality, latency, and cost for most common use cases.155- **`low`:** Use for scenarios where cost and latency are paramount, and fine-grained detail is less critical.156- **`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.157- **`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`.158- **Per-content-item control (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.159160**Recommended settings**161162The following lists the recommended media resolution settings for each supported media type.163164| Media Type | Recommended Setting | Max Tokens | Usage Guidance |165|---|---|---|---|166| **Images** | `high` | 1120 | Recommended for most image analysis tasks to ensure maximum quality. |167| **PDFs** | `medium` | 560 | Optimal for document understanding; quality typically saturates at `medium`. Increasing to `high` rarely improves OCR results for standard documents. |168| **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. |169| **Video** (Text-heavy) | `high` | 280 (per frame) | Required only when the use case involves reading dense text (OCR) or small details within video frames. |170| **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`). |171172Always test and evaluate the impact of different resolution settings on your application to find the best trade-off between quality, latency, and cost.173174## Relationship with video processing modes175176The `media_resolution` and processing parameters control different aspects of video input:177178- `media_resolution` controls the **resolution** of each frame (number of tokens per frame).179- `processing` / `media_processing` controls **which content from the video** is loaded into context.180181You can set both on the same video input. For example, you might use agentic processing with low media resolution to minimize total token usage for a long video.182183For details on video processing modes, see the [Agentic video understanding](https://ai.google.dev/gemini-api/docs/video-understanding#agentic-video-understanding) guide.184185## Version compatibility summary186187- Setting the `resolution` on individual content items is **exclusive to Gemini 3 models**.188189## Next steps190191- Learn more about the multimodal capabilities of Gemini API in the [image understanding](https://ai.google.dev/gemini-api/docs/image-understanding), [video understanding](https://ai.google.dev/gemini-api/docs/video-understanding), [audio understanding](https://ai.google.dev/gemini-api/docs/audio), and [document understanding](https://ai.google.dev/gemini-api/docs/document-processing) guides.