Repository Public
1# Media resolution23> [!NOTE]4> **Note** : This version of the page covers the new [Interactions API](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview), which is currently in Beta. 5> For stable production deployments, we recommend you continue to use the `generateContent` API. You can use the toggle on this page to switch between the versions.67The `media_resolution` parameter controls how the Gemini API processes media inputs like images, videos, and PDF documents by determining the **maximum number of tokens** allocated for media inputs, allowing you to balance response quality against latency and cost. For different settings, default values and how they correspond to tokens, see the [Token counts](https://ai.google.dev/gemini-api/docs/interactions/media-resolution#token-counts) section.89You can configure media resolution for individual media objects (content items) within your request (Gemini 3 only).1011## Per-content-item media resolution (Gemini 3 only)1213Gemini 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.1415### Python1617 from google import genai1819 client = genai.Client()2021 myfile = client.files.upload(file="path/to/image.jpg")2223 interaction = client.interactions.create(24 model="gemini-3.5-flash",25 input=[26 {"type": "text", "text": "Describe this image:"},27 {28 "type": "image",29 "uri": myfile.uri,30 "mime_type": myfile.mime_type,31 "resolution": "high"32 }33 ]34 )35 print(interaction.output_text)3637### JavaScript3839 import { GoogleGenAI } from "@google/genai";4041 const ai = new GoogleGenAI({});4243 async function main() {44 const myfile = await ai.files.upload({45 file: "path/to/image.jpg",46 config: { mime_type: "image/jpeg" },47 });4849 const interaction = await ai.interactions.create({50 model: "gemini-3.5-flash",51 input: [52 { type: "text", text: "Describe this image:" },53 {54 type: "image",55 uri: myfile.uri,56 mime_type: myfile.mimeType,57 resolution: "high"58 }59 ],60 });61 console.log(interaction.output_text);62 }6364 await main();6566### REST6768 # First upload the file using the Files API, then use the URI:69 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \70 -H "x-goog-api-key: $GEMINI_API_KEY" \71 -H 'Content-Type: application/json' \72 -H "Api-Revision: 2026-05-20" \73 -d '{74 "model": "gemini-3.5-flash",75 "input": [76 {"type": "text", "text": "Describe this image:"},77 {78 "type": "image",79 "uri": "YOUR_FILE_URI",80 "mime_type": "image/jpeg",81 "resolution": "high"82 }83 ]84 }'8586## Available resolution values8788The Gemini API defines the following levels for media resolution:8990- `unspecified`: The default setting. The token count for this level varies significantly between Gemini 3 and earlier Gemini models.91- `low`: Lower token count, resulting in faster processing and lower cost, but with less detail.92- `medium`: A balance between detail, cost, and latency.93- `high`: Higher token count, providing more detail for the model to work with, at the expense of increased latency and cost.94- `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/interactions/computer-use).9596Note that `high` provides the optimal performance for most use cases.9798The exact number of tokens generated for each of these levels depends on both the **media type** (Image, Video, PDF) and the **model version**.99100## Token counts101102The tables below summarize the approximate token counts for each `media_resolution` value and media type per model family.103104**Gemini 3 models**105106| MediaResolution | Image | Video | PDF |107|---|---|---|---|108| `unspecified` (Default) | 1120 | 70 | 560 |109| `low` | 280 | 70 | 280 + Native Text |110| `medium` | 560 | 70 | 560 + Native Text |111| `high` | 1120 | 280 | 1120 + Native Text |112| `ultra_high` | 2240 | N/A | N/A |113114## Choosing the right resolution115116- **Default (`unspecified`):** Start with the default. It's tuned for a good balance of quality, latency, and cost for most common use cases.117- **`low`:** Use for scenarios where cost and latency are paramount, and fine-grained detail is less critical.118- **`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.119- **`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`.120- **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.121122**Recommended settings**123124The following lists the recommended media resolution settings for each supported media type.125126| Media Type | Recommended Setting | Max Tokens | Usage Guidance |127|---|---|---|---|128| **Images** | `high` | 1120 | Recommended for most image analysis tasks to ensure maximum quality. |129| **PDFs** | `medium` | 560 | Optimal for document understanding; quality typically saturates at `medium`. Increasing to `high` rarely improves OCR results for standard documents. |130| **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. |131| **Video** (Text-heavy) | `high` | 280 (per frame) | Required only when the use case involves reading dense text (OCR) or small details within video frames. |132133Always test and evaluate the impact of different resolution settings on your application to find the best trade-off between quality, latency, and cost.134135## Version compatibility summary136137- Setting the `resolution` on individual content items is **exclusive to Gemini 3 models**.138139## Next steps140141- Learn more about the multimodal capabilities of Gemini API in the [image understanding](https://ai.google.dev/gemini-api/docs/interactions/image-understanding), [video understanding](https://ai.google.dev/gemini-api/docs/interactions/video-understanding) and [document understanding](https://ai.google.dev/gemini-api/docs/interactions/document-processing) guides.