Guide du développeur Gemini 3 (original) (raw)

Passer au contenu principal

Gemini 3 est notre famille de modèles la plus intelligente à ce jour. Elle repose sur une technologie de raisonnement à la pointe du secteur. Il est conçu pour donner vie à toutes vos idées 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.

Testez Gemini 3 Pro sans frais

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.

Commencez avec quelques lignes de code :

Python

from google import genai

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)

JavaScript

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();

REST

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]"}]
    }]
  }'

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é à vos tâches complexes qui nécessitent une vaste connaissance du monde et un raisonnement avancé dans plusieurs modalités.

ID du modèle Fenêtre de contexte (entrée / sortie) Date limite des connaissances Tarification (entrée / sortie)*
gemini-3-pro-preview 1 M / 64 k Janv. 2025 2 $ / 12 $ (< 200 000 jetons) 4 $ / 18 $ (> 200 000 jetons)
gemini-3-pro-image-preview 65 000 / 32 000 Janv. 2025 2 $ (entrée de texte) / 0,134 $ (sortie d'image)**

* Sauf indication contraire, les tarifs s'entendent pour 1 million de jetons. ** Le prix des images varie en fonction de la résolution. Pour en savoir plus, consultez la page des tarifs.

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

Gemini 3 Pro utilise par défaut la pensée dynamique pour traiter les requêtes. Vous pouvez utiliser le paramètre thinking_level, qui 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. 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.

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents="How does AI work?",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)

print(response.text)

JavaScript

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

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
    model: "gemini-3-pro-preview",
    contents: "How does AI work?",
    config: {
      thinkingConfig: {
        thinkingLevel: "low",
      }
    },
  });

console.log(response.text);

REST

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": "How does AI work?"}]
    }],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingLevel": "low"
      }
    }
  }'

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, media_resolution_high ou media_resolution_ultra_high pour chaque partie multimédia ou de manière globale (via generation_config, la résolution globale n'est pas disponible pour l'ultra haute définition). Si aucune valeur n'est spécifiée, le modèle utilise les valeurs par défaut optimales en fonction du type de support.

Paramètres recommandés

Type de support Réglage recommandé Nombre maximal de jetons Conseils d'utilisation
Images media_resolution_high 1120 Recommandé pour la plupart des tâches d'analyse d'images afin de garantir une qualité maximale.
PDF media_resolution_medium 560 Idéal pour la compréhension des documents. La qualité atteint généralement son maximum à medium. Augmenter la valeur à high améliore rarement les résultats de l'OCR pour les documents standards.
Vidéo (général) media_resolution_low (ou media_resolution_medium) 70 (par frame) Remarque : Pour les vidéos, les paramètres low et medium sont traités de manière identique (70 jetons) afin d'optimiser l'utilisation du contexte. Cela suffit pour la plupart des tâches de reconnaissance et de description d'actions.
Vidéo (avec beaucoup de texte) media_resolution_high 280 (par frame) Obligatoire uniquement lorsque le cas d'utilisation implique la lecture de texte dense (OCR) ou de petits détails dans les images vidéo.

.

Python

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)

JavaScript

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();

REST

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 (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.

Texte et streaming

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

Génération et modification d'images

Pour gemini-3-pro-image-preview, les signatures de pensée sont essentielles pour la modification conversationnelle. Lorsque vous demandez au modèle de modifier une image, il s'appuie sur le thoughtSignature du tour précédent pour comprendre la composition et la logique de l'image d'origine.

Exemples de code

Appel de fonction en plusieurs étapes (séquentiel)

L'utilisateur pose une question nécessitant deux étapes distinctes (vérifier le vol > réserver un taxi) en une seule fois.

Étape 1 : Le modèle appelle l'outil de vol.
Le modèle renvoie une signature <Sig_A>

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

Étape 2 : L'utilisateur envoie le résultat du vol
Nous devons renvoyer <Sig_A> pour maintenir le fil de pensée du modèle.

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

Étape 3 : Le modèle appelle l'outil de taxi
Le modèle se souvient du retard du vol grâce à <Sig_A> et décide maintenant de réserver un taxi. Il génère une nouvelle signature <Sig_B>.

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

Étape 4 : L'utilisateur envoie le résultat du taxi
Pour terminer le tour, vous devez renvoyer la chaîne complète : <Sig_A> ET <Sig_B>.

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

Appel de fonction en parallèle

L'utilisateur demande : "Vérifie la météo à Paris et à Londres." Le modèle renvoie deux appels de fonction dans une seule réponse.

// 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": "" }, // 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" } } } ] } ]

Texte/Raisonnement dans le contexte (sans validation)

L'utilisateur pose une question qui nécessite un raisonnement contextuel sans outils externes. Bien qu'elle ne soit pas strictement validée, l'inclusion de la signature aide le modèle à maintenir la chaîne de raisonnement pour les questions de suivi.

// 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": "" // Recommended to include } ] }, { "role": "user", "parts": [{ "text": "Summarize that in one sentence." }] } ]

Génération et modification d'images

Pour la génération d'images, les signatures sont strictement validées. Elles s'affichent sur la première partie (texte ou image) et sur toutes les parties d'image suivantes. Tous doivent être renvoyés au prochain tour.

// Model Response (Turn 1) { "role": "model", "parts": [ // 1. First part ALWAYS has a signature (even if text) { "text": "I will generate a cyberpunk city...", "thoughtSignature": "" }, // 2. ALL InlineData (Image) parts ALWAYS have signatures { "inlineData": { ... }, "thoughtSignature": "" }, ] }

// User Request (Turn 2 - Requesting an Edit) { "contents": [ // History must include ALL signatures received { "role": "user", "parts": [{ "text": "Generate a cyberpunk city" }] }, { "role": "model", "parts": [ { "text": "...", "thoughtSignature": "" }, { "inlineData": "...", "thoughtSignature": "" }, ] }, // New User Prompt { "role": "user", "parts": [{ "text": "Make it daytime." }] } ] }

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.

Python

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)

JavaScript

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();

REST

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"]
        }
    }
  }'

Génération d'images

Gemini 3 Pro Image vous permet de générer et de modifier des images à partir de requêtes textuelles. Il utilise le raisonnement pour "réfléchir" à une requête et peut récupérer des données en temps réel (comme des prévisions météo ou des graphiques boursiers) avant d'utiliser l'ancrage Recherche Google pour générer des images haute fidélité.

Nouvelles fonctionnalités et améliorations :

Pour en savoir plus sur les formats, les workflows de modification et les options de configuration, consultez le guide sur la génération d'images.

Python

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-pro-image-preview",
    contents="Generate an infographic of the current weather in Tokyo.",
    config=types.GenerateContentConfig(
        tools=[{"google_search": {}}],
        image_config=types.ImageConfig(
            aspect_ratio="16:9",
            image_size="4K"
        )
    )
)

image_parts = [part for part in response.parts if part.inline_data]

if image_parts:
    image = image_parts[0].as_image()
    image.save('weather_tokyo.png')
    image.show()

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});

async function run() {
  const response = await ai.models.generateContent({
    model: "gemini-3-pro-image-preview",
    contents: "Generate a visualization of the current weather in Tokyo.",
    config: {
      tools: [{ googleSearch: {} }],
      imageConfig: {
        aspectRatio: "16:9",
        imageSize: "4K"
      }
    }
  });

  for (const part of response.candidates[0].content.parts) {
    if (part.inlineData) {
      const imageData = part.inlineData.data;
      const buffer = Buffer.from(imageData, "base64");
      fs.writeFileSync("weather_tokyo.png", buffer);
    }
  }
}

run();

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Generate a visualization of the current weather in Tokyo."}]
    }],
    "tools": [{"googleSearch": {}}],
    "generationConfig": {
        "imageConfig": {
          "aspectRatio": "16:9",
          "imageSize": "4K"
      }
    }
  }'

Exemple de réponse

Météo à Tokyo

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 :

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 :

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.

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 forfait 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 accepté pour 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 les fonctionnalités Ancrage avec Google Maps et Utilisation de l'ordinateur ne sont pas disponibles pour le moment.

Étapes suivantes

Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.

Dernière mise à jour le 2025/12/06 (UTC).