Guide du développeur Gemini 3

Gemini 3 est notre famille de modèles la plus intelligente à ce jour, basée sur un raisonnement de pointe. Il est conçu pour donner vie à n'importe quelle idée en maîtrisant les workflows agentifs, le codage autonome et les tâches multimodales complexes. Ce guide présente les principales fonctionnalités de la famille de modèles Gemini 3 et explique comment en tirer le meilleur parti.

Pensée dynamique/élevée Pensée faible

Gemini 3 Pro utilise par défaut la pensée dynamique pour traiter les requêtes. Pour obtenir des réponses plus rapides et à faible latence lorsque le raisonnement complexe n'est pas nécessaire, vous pouvez limiter le niveau de réflexion du modèle à low.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
)

print(response.text)

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents="Find the race condition in this multi-threaded C++ snippet: [code here]",
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Find the race condition in this multi-threaded C++ snippet: [code here]"}]
    }]
  }'

Explorer

Découvrez notre collection d'applications Gemini 3 pour voir comment le modèle gère le raisonnement avancé, le codage autonome et les tâches multimodales complexes.

Découvrez Gemini 3

Gemini 3 Pro est le premier modèle de la nouvelle série. gemini-3-pro-preview est le mieux adapté aux tâches complexes qui nécessitent une vaste connaissance du monde et un raisonnement avancé dans plusieurs modalités.

* Les tarifs sont indiqués pour un million de jetons. Les prix indiqués concernent le texte standard. Les tarifs des entrées multimodales peuvent varier.

Pour en savoir plus sur les limites de débit, les tarifs par lot et d'autres informations, consultez la page des modèles.

Nouvelles fonctionnalités de l'API dans Gemini 3

Gemini 3 introduit de nouveaux paramètres conçus pour donner aux développeurs plus de contrôle sur la latence, les coûts et la fidélité multimodale.

Niveau de réflexion

Le paramètre thinking_level contrôle la profondeur maximale du processus de raisonnement interne du modèle avant qu'il ne produise une réponse. Gemini 3 traite ces niveaux comme des allocations relatives pour la réflexion plutôt que comme des garanties strictes de jetons. Si thinking_level n'est pas spécifié, Gemini 3 Pro utilisera high par défaut.

• low : minimise la latence et les coûts. Idéal pour les applications de suivi d'instructions simples, de chat ou à haut débit
• medium : (bientôt disponible), non compatible au lancement
• high (par défaut) : maximise la profondeur du raisonnement. Le modèle peut mettre beaucoup plus de temps à générer le premier jeton, mais le résultat sera plus réfléchi.

Résolution du contenu multimédia

Gemini 3 introduit un contrôle précis sur le traitement de la vision multimodale grâce au paramètre media_resolution. Les résolutions plus élevées améliorent la capacité du modèle à lire du texte fin ou à identifier de petits détails, mais augmentent l'utilisation de jetons et la latence. Le paramètre media_resolution détermine le nombre maximal de jetons alloués par image ou frame vidéo en entrée.

Vous pouvez désormais définir la résolution sur media_resolution_low, media_resolution_medium ou media_resolution_high pour chaque partie média ou globalement (via generation_config). Si aucune résolution n'est spécifiée, le modèle utilise les paramètres par défaut optimaux en fonction du type de média.

Paramètres recommandés

from google import genai
from google.genai import types
import base64

# The media_resolution parameter is currently only available in the v1alpha API version.
client = genai.Client(http_options={'api_version': 'v1alpha'})

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=[
        types.Content(
            parts=[
                types.Part(text="What is in this image?"),
                types.Part(
                    inline_data=types.Blob(
                        mime_type="image/jpeg",
                        data=base64.b64decode("..."),
                    ),
                    media_resolution={"level": "media_resolution_high"}
                )
            ]
        )
    ]
)

print(response.text)

import { GoogleGenAI } from "@google/genai";

// The media_resolution parameter is currently only available in the v1alpha API version.
const ai = new GoogleGenAI({ apiVersion: "v1alpha" });

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: [
      {
        parts: [
          { text: "What is in this image?" },
          {
            inlineData: {
              mimeType: "image/jpeg",
              data: "...",
            },
            mediaResolution: {
              level: "media_resolution_high"
            }
          }
        ]
      }
    ]
  });

  console.log(response.text);
}

run();

curl "https://generativelanguage.googleapis.com/v1alpha/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [
        { "text": "What is in this image?" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "..."
          },
          "mediaResolution": {
            "level": "media_resolution_high"
          }
        }
      ]
    }]
  }'

Température

Pour Gemini 3, nous vous recommandons vivement de conserver la valeur par défaut du paramètre de température, à savoir 1.0.

Alors que les modèles précédents bénéficiaient souvent d'un réglage de la température pour contrôler la créativité par rapport au déterminisme, les capacités de raisonnement de Gemini 3 sont optimisées pour le paramètre par défaut. Si vous modifiez la température (en la définissant sur une valeur inférieure à 1,0), vous risquez d'obtenir un comportement inattendu, comme des boucles ou une dégradation des performances, en particulier pour les tâches mathématiques ou de raisonnement complexes.

Signatures de pensée

Gemini 3 utilise des signatures de pensée pour conserver le contexte de raisonnement entre les appels d'API. Ces signatures sont des représentations chiffrées du processus de réflexion interne du modèle. Pour vous assurer que le modèle conserve ses capacités de raisonnement, vous devez renvoyer ces signatures au modèle dans votre requête exactement telles qu'elles ont été reçues :

• Appel de fonction (strict) : l'API applique une validation stricte au "tour actuel". Si des signatures manquent, une erreur 400 sera générée.
• Texte/Chat : la validation n'est pas strictement appliquée, mais l'omission des signatures dégradera la qualité du raisonnement et des réponses du modèle.

Appel de fonction (validation stricte)

Lorsque Gemini génère un functionCall, il s'appuie sur le thoughtSignature pour traiter correctement la sortie de l'outil au tour suivant. Le "tour actuel" inclut toutes les étapes de modèle (functionCall) et d'utilisateur (functionResponse) qui se sont produites depuis le dernier message text Utilisateur standard.

• Appel de fonction unique : la partie functionCall contient une signature. Vous devez le renvoyer.
• Appels de fonction parallèles : seule la première partie functionCall de la liste contient la signature. Vous devez retourner les pièces dans l'ordre exact dans lequel vous les avez reçues.
• Multiples étapes (séquentielles) : si le modèle appelle un outil, reçoit un résultat et appelle un autre outil (au cours du même tour), les deux appels de fonction ont des signatures. Vous devez renvoyer toutes les signatures accumulées dans l'historique.

Texte et streaming

Pour la génération de texte ou le chat standard, la présence d'une signature n'est pas garantie.

• Non-Streaming : la partie finale du contenu de la réponse peut contenir un thoughtSignature, mais ce n'est pas toujours le cas. Si vous en recevez un, renvoyez-le pour maintenir des performances optimales.
• Streaming : si une signature est générée, elle peut arriver dans un bloc final contenant une partie de texte vide. Assurez-vous que votre analyseur de flux recherche les signatures même si le champ de texte est vide.

Exemples de code

// Model Response (Turn 1, Step 1)
  {
    "role": "model",
    "parts": [
      {
        "functionCall": { "name": "check_flight", "args": {...} },
        "thoughtSignature": "<Sig_A>" // SAVE THIS
      }
    ]
  }

// User Request (Turn 1, Step 2)
[
  { "role": "user", "parts": [{ "text": "Check flight AA100..." }] },
  { 
    "role": "model", 
    "parts": [
      { 
        "functionCall": { "name": "check_flight", "args": {...} }, 
        "thoughtSignature": "<Sig_A>" // REQUIRED
      } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": { "name": "check_flight", "response": {...} } }] }
]

// Model Response (Turn 1, Step 3)
{
  "role": "model",
  "parts": [
    {
      "functionCall": { "name": "book_taxi", "args": {...} },
      "thoughtSignature": "<Sig_B>" // SAVE THIS
    }
  ]
}

// User Request (Turn 1, Step 4)
[
  // ... previous history ...
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "check_flight", ... }, "thoughtSignature": "<Sig_A>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] },
  { 
    "role": "model", 
    "parts": [
       { "functionCall": { "name": "book_taxi", ... }, "thoughtSignature": "<Sig_B>" } 
    ]
  },
  { "role": "user", "parts": [{ "functionResponse": {...} }] }
]

// User Request (Sending Parallel Results)
[
  {
    "role": "user",
    "parts": [
      { "text": "Check the weather in Paris and London." }
    ]
  },
  {
    "role": "model",
    "parts": [
      // 1. First Function Call has the signature
      {
        "functionCall": { "name": "check_weather", "args": { "city": "Paris" } },
        "thoughtSignature": "<Signature_A>" 
      },
      // 2. Subsequent parallel calls DO NOT have signatures
      {
        "functionCall": { "name": "check_weather", "args": { "city": "London" } }
      } 
    ]
  },
  {
    "role": "user",
    "parts": [
      // 3. Function Responses are grouped together in the next block
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "15C" } }
      },
      {
        "functionResponse": { "name": "check_weather", "response": { "temp": "12C" } }
      }
    ]
  }
]

// User Request (Follow-up question)
[
  { 
    "role": "user", 
    "parts": [{ "text": "What are the risks of this investment?" }] 
  },
  { 
    "role": "model", 
    "parts": [
      {
        "text": "I need to calculate the risk step-by-step. First, I'll look at volatility...",
        "thoughtSignature": "<Signature_C>" // Recommended to include
      }
    ]
  },
  { 
    "role": "user", 
    "parts": [{ "text": "Summarize that in one sentence." }] 
  }
]

Migrer depuis d'autres modèles

Si vous transférez une trace de conversation depuis un autre modèle (par exemple, Gemini 2.5) ou en injectant un appel de fonction personnalisé qui n'a pas été généré par Gemini 3, vous n'aurez pas de signature valide.

Pour contourner la validation stricte dans ces scénarios spécifiques, remplissez le champ avec cette chaîne factice spécifique : "thoughtSignature": "context_engineering_is_the_way_to_go".

Sorties structurées avec des outils

Gemini 3 vous permet de combiner les sorties structurées avec des outils intégrés, y compris l'ancrage avec la recherche Google, le contexte d'URL et l'exécution de code.

from google import genai
from google.genai import types
from pydantic import BaseModel, Field
from typing import List

class MatchResult(BaseModel):
    winner: str = Field(description="The name of the winner.")
    final_match_score: str = Field(description="The final match score.")
    scorers: List[str] = Field(description="The name of the scorer.")

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="Search for all details for the latest Euro.",
    config={
        "tools": [
            {"google_search": {}},
            {"url_context": {}}
        ],
        "response_mime_type": "application/json",
        "response_json_schema": MatchResult.model_json_schema(),
    },  
)

result = MatchResult.model_validate_json(response.text)
print(result)

import { GoogleGenAI } from "@google/genai";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const ai = new GoogleGenAI({});

const matchSchema = z.object({
  winner: z.string().describe("The name of the winner."),
  final_match_score: z.string().describe("The final score."),
  scorers: z.array(z.string()).describe("The name of the scorer.")
});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "Search for all details for the latest Euro.",
    config: {
      tools: [
        { googleSearch: {} },
        { urlContext: {} }
      ],
      responseMimeType: "application/json",
      responseJsonSchema: zodToJsonSchema(matchSchema),
    },
  });

  const match = matchSchema.parse(JSON.parse(response.text));
  console.log(match);
}

run();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Search for all details for the latest Euro."}]
    }],
    "tools": [
      {"googleSearch": {}},
      {"urlContext": {}}
    ],
    "generationConfig": {
        "responseMimeType": "application/json",
        "responseJsonSchema": {
            "type": "object",
            "properties": {
                "winner": {"type": "string", "description": "The name of the winner."},
                "final_match_score": {"type": "string", "description": "The final score."},
                "scorers": {
                    "type": "array",
                    "items": {"type": "string"},
                    "description": "The name of the scorer."
                }
            },
            "required": ["winner", "final_match_score", "scorers"]
        }
    }
  }'

Migrer depuis Gemini 2.5

Gemini 3 est notre famille de modèles la plus performante à ce jour. Elle offre une amélioration progressive par rapport à Gemini 2.5 Pro. Lorsque vous effectuez une migration, tenez compte des points suivants :

• Réflexion : si vous utilisiez auparavant des techniques d'ingénierie des requêtes complexes (comme Chain-of-thought) pour forcer Gemini 2.5 à raisonner, essayez Gemini 3 avec thinking_level: "high" et des requêtes simplifiées.
• Paramètres de température : si votre code existant définit explicitement la température (en particulier sur des valeurs basses pour des résultats déterministes), nous vous recommandons de supprimer ce paramètre et d'utiliser la valeur par défaut de Gemini 3, à savoir 1.0, pour éviter d'éventuels problèmes de boucle ou une dégradation des performances pour les tâches complexes.
• Compréhension des PDF et des documents : la résolution OCR par défaut pour les PDF a changé. Si vous vous êtes appuyé sur un comportement spécifique pour l'analyse des documents denses, testez le nouveau paramètre media_resolution_high pour vous assurer de la précision continue.
• Consommation de jetons : la migration vers les paramètres par défaut de Gemini 3 Pro peut augmenter l'utilisation de jetons pour les PDF, mais la diminuer pour les vidéos. Si les requêtes dépassent désormais la fenêtre de contexte en raison de résolutions par défaut plus élevées, nous vous recommandons de réduire explicitement la résolution du contenu multimédia.
• Segmentation d'images : les fonctionnalités de segmentation d'images (qui renvoient des masques au niveau des pixels pour les objets) ne sont pas disponibles dans Gemini 3 Pro. Pour les charges de travail nécessitant une segmentation d'image native, nous vous recommandons de continuer à utiliser Gemini 2.5 Flash avec la réflexion désactivée ou Gemini Robotics-ER 1.5.

Compatibilité avec OpenAI

Pour les utilisateurs qui utilisent la couche de compatibilité OpenAI, les paramètres standards sont automatiquement mappés sur les équivalents Gemini :

• reasoning_effort (OAI) correspond à thinking_level (Gemini). Notez que le niveau moyen de reasoning_effort correspond au niveau élevé de thinking_level.

Bonnes pratiques concernant les requêtes

Gemini 3 est un modèle de raisonnement, ce qui modifie la façon dont vous devez formuler vos requêtes.

• Instructions précises : soyez concis dans vos requêtes. Gemini 3 répond mieux aux instructions directes et claires. Il peut suranalyser les techniques d'ingénierie des requêtes verbeuses ou trop complexes utilisées pour les anciens modèles.
• Niveau de détail des réponses : par défaut, Gemini 3 est moins bavard et préfère fournir des réponses directes et efficaces. Si votre cas d'utilisation nécessite une personnalité plus conversationnelle ou "bavarde", vous devez orienter explicitement le modèle dans la requête (par exemple, "Explique-moi cela comme un assistant amical et bavard").
• Gestion du contexte : lorsque vous travaillez avec de grands ensembles de données (par exemple, des livres entiers, des bases de code ou de longues vidéos), placez vos instructions ou questions spécifiques à la fin de la requête, après le contexte des données. Ancrez le raisonnement du modèle aux données fournies en commençant votre question par une expression telle que "Sur la base des informations ci-dessus…".

Pour en savoir plus sur les stratégies de conception de requêtes, consultez le guide sur l'ingénierie des requêtes.

Questions fréquentes

1. Quelle est la limite de connaissances pour Gemini 3 Pro ? La limite de connaissances de Gemini 3 est fixée à janvier 2025. Pour obtenir des informations plus récentes, utilisez l'outil Search Grounding.

2. Quelles sont les limites de la fenêtre de contexte ? Gemini 3 Pro accepte une fenêtre de contexte d'entrée d'un million de jetons et jusqu'à 64 000 jetons de sortie.

3. Existe-t-il un niveau sans frais pour Gemini 3 Pro ? Vous pouvez essayer le modèle sans frais dans Google AI Studio, mais aucun niveau sans frais n'est actuellement disponible pour gemini-3-pro-preview dans l'API Gemini.

4. Mon ancien code thinking_budget fonctionnera-t-il toujours ? Oui, thinking_budget est toujours compatible pour assurer la rétrocompatibilité, mais nous vous recommandons de migrer vers thinking_level pour des performances plus prévisibles. Ne les utilisez pas toutes les deux dans la même requête.

5. Gemini 3 est-il compatible avec l'API Batch ? Oui, Gemini 3 est compatible avec l'API Batch.

6. La mise en cache du contexte est-elle prise en charge ? Oui, la mise en cache du contexte est compatible avec Gemini 3. Le nombre minimal de jetons requis pour lancer la mise en cache est de 2 048.

7. Quels outils sont compatibles avec Gemini 3 ? Gemini 3 est compatible avec la recherche Google, la recherche de fichiers, l'exécution de code et le contexte d'URL. Il est également compatible avec l'appel de fonction standard pour vos propres outils personnalisés. Veuillez noter que Google Maps et l'utilisation d'un ordinateur ne sont pas compatibles pour le moment.

Étapes suivantes

• Premiers pas avec le livre de recettes Gemini 3
• Consultez le guide Cookbook dédié aux niveaux de réflexion et découvrez comment migrer du budget de réflexion vers les niveaux de réflexion.