Résolution multimédia

Le paramètre media_resolution contrôle la façon dont l'API Gemini traite les entrées multimédias telles que les images, les vidéos, les fichiers audio et les documents PDF en déterminant le nombre maximal de jetons alloués aux entrées multimédias. Vous pouvez ainsi équilibrer la qualité de la réponse par rapport à la latence et au coût. Alors que les entrées visuelles et de documents mettent à l'échelle l'allocation de jetons en fonction du paramètre de résolution, les entrées audio sont tokenisées à un débit fixe par seconde pour tous les niveaux de résolution. Pour connaître les différents paramètres, les valeurs par défaut et leur correspondance avec les jetons, consultez la section Nombre de jetons.

Vous pouvez configurer la résolution multimédia de deux manières :

• Par partie (modèles Gemini 4 et Gemini 3)

• Globalement pour une requête generateContent entière (tous les modèles multimodaux)

Résolution multimédia par partie (Gemini 4 et Gemini 3)

Gemini 4 et Gemini 3 vous permettent de définir la résolution multimédia pour des objets multimédias individuels dans votre requête, ce qui vous offre une optimisation précise de l'utilisation des jetons. Vous pouvez combiner différents niveaux de résolution dans une même requête. Par exemple, vous pouvez utiliser une haute résolution pour un diagramme complexe et une basse résolution pour une image contextuelle. Ce paramètre remplace toute configuration globale pour une partie spécifique. Pour connaître les paramètres par défaut, consultez la section Nombre de jetons.

from google import genai
from google.genai import types

# The media_resolution parameter for parts is available in the v1beta API version.
client = genai.Client(
  http_options={
      'api_version': 'v1beta',
  }
)

# 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-4-argon'

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: 'v1beta' } });

// 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-4-argon';
    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-4-argon"

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/v1beta/models/${MODEL_ID}:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Résolution multimédia globale

Vous pouvez définir une résolution par défaut pour toutes les parties de contenu multimédia d'une requête à l'aide de GenerationConfig. Cette fonctionnalité est compatible avec tous les modèles multimodaux. Si une requête inclut à la fois des paramètres globaux et par partie, le paramètre par partie est prioritaire pour cet élément spécifique.

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.8-flash',
    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.8-flash',
      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.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [...],
    "generation_config": {
      "media_resolution": "MEDIA_RESOLUTION_HIGH"
    }
  }'

Valeurs de résolution disponibles

L'API Gemini définit les niveaux suivants pour la résolution multimédia :

• MEDIA_RESOLUTION_UNSPECIFIED : paramètre par défaut. Le nombre de jetons pour ce niveau varie considérablement entre Gemini 3 et les modèles Gemini antérieurs.
• MEDIA_RESOLUTION_LOW: nombre de jetons inférieur, ce qui permet un traitement plus rapide et un coût plus faible, mais avec moins de détails.
• MEDIA_RESOLUTION_MEDIUM : équilibre entre détails, coût et latence.
• MEDIA_RESOLUTION_HIGH: nombre de jetons plus élevé, ce qui fournit plus de détails au modèle, mais augmente la latence et le coût.
• MEDIA_RESOLUTION_ULTRA_HIGH (par partie uniquement) : nombre de jetons le plus élevé, requis pour des cas d'utilisation spécifiques tels que l'utilisation d'un ordinateur.

Notez que MEDIA_RESOLUTION_HIGH offre des performances optimales pour la plupart des cas d'utilisation.

Le nombre exact de jetons générés pour chacun de ces niveaux dépend à la fois du type de média (image, vidéo, audio, PDF) et de la version du modèle.

Nombre de jetons

Les tableaux ci-dessous récapitulent le nombre approximatif de jetons pour chaque valeur media_resolution et type de média par famille de modèles.

Modèles Gemini 3

Modèles Gemini 2.5

Choisir la bonne résolution

• Par défaut (UNSPECIFIED) : commencez par la valeur par défaut. Elle est optimisée pour un bon équilibre entre qualité, latence et coût pour la plupart des cas d'utilisation courants.
• LOW : utilisez cette valeur dans les scénarios où le coût et la latence sont primordiaux, et où les détails précis sont moins importants.
• MEDIUM / HIGH : augmentez la résolution lorsque la tâche nécessite de comprendre des détails complexes dans le média. Cela est souvent nécessaire pour une analyse visuelle complexe, la lecture de graphiques ou la compréhension de documents denses.
• ULTRA HIGH : disponible uniquement pour le paramètre par partie. Recommandé pour des cas d'utilisation spécifiques tels que l'utilisation d'un ordinateur ou lorsque les tests montrent une amélioration claire par rapport à HIGH.
• Contrôle par partie (Gemini 4 et Gemini 3) : optimise l'utilisation des jetons. Par exemple, dans une invite comportant plusieurs images, utilisez HIGH pour un diagramme complexe et LOW ou MEDIUM pour des images contextuelles plus simples.

Paramètres recommandés

La liste suivante indique les paramètres de résolution multimédia recommandés pour chaque type de média compatible.

Testez et évaluez toujours l'impact des différents paramètres de résolution sur votre application spécifique afin de trouver le meilleur compromis entre qualité, latence et coût.

Relation avec les modes de traitement vidéo

Les paramètres media_resolution et de traitement contrôlent différents aspects de l'entrée vidéo :

• media_resolution contrôle la résolution de chaque image (nombre de jetons par image).
• processing / media_processing contrôle le contenu de la vidéo qui est chargé dans le contexte.

Vous pouvez définir les deux sur la même entrée vidéo. Par exemple, vous pouvez utiliser le traitement agentique avec une faible résolution multimédia pour minimiser l'utilisation totale de jetons pour une longue vidéo.

Pour en savoir plus sur les modes de traitement vidéo, consultez le guide Comprendre les vidéos agentiques.

Résumé de la compatibilité des versions

• L'énumération MediaResolution est disponible pour tous les modèles compatibles avec l'entrée multimédia.
• Le nombre de jetons associé à chaque niveau d'énumération diffère entre les modèles Gemini 4 / Gemini 3 et les versions Gemini antérieures.
• La définition de media_resolution sur des objets Part individuels est compatible avec les modèles Gemini 4 et Gemini 3.

Étapes suivantes

• Pour en savoir plus sur les fonctionnalités multimodales de l'API Gemini, consultez les guides Comprendre les images, Comprendre les vidéos, Comprendre l'audio et Comprendre les documents.