Guide du développeur pour Gemini 4 Carbon

Gemini 4 Carbon est le modèle de frontière de Google qui excelle dans le travail approfondi sur des tâches complexes et réelles dans des domaines tels que le codage, la finance, le droit, la cybersécurité et la science. Il fait partie de la famille Gemini 4. Gemini 4 Carbon est un modèle de frontière Google soumis à la section 34 des Conditions spécifiques du service (pour en savoir plus, consultez Surveillance des utilisations abusives).

Ce document présente les principales fonctionnalités de 4 Carbon, les conventions d'API qu'il applique, la procédure de migration et un guide de démarrage rapide. Pour une présentation de la famille Gemini 4, consultez Premiers pas avec Gemini 4.

Principales fonctionnalités de Gemini 4 Carbon

Gemini 4 Carbon inclut les fonctionnalités suivantes :

• Limite unifiée de jetons d'entrée et de sortie : 4 Carbon a une limite unifiée de 1 048 576 jetons qui inclut à la fois les jetons d'entrée et de sortie (où la sortie inclut la réflexion, les appels de fonction et la réponse finale).
• Décodages longs jusqu'à 1 048 576 jetons : 4 Carbon étend la génération au-delà d'un seul segment de premier plan (65 536 jetons en streaming ou 32 768 jetons en non-streaming) jusqu'à 1 048 576 jetons (moins vos jetons d'entrée) sur l'API Interactions et GenerateContent (v1beta1). Le SDK Google Gen AI gère automatiquement continuation_token sur plusieurs segments. Vous pouvez également exécuter des décodages asynchrones en arrière-plan gérés par le serveur (background=true) ou gérer continuation_token dans une boucle de continuation personnalisée.
• Niveaux de réflexion : 4 Carbon est compatible avec LOW, MEDIUM (par défaut sur gemini-4-carbon) et HIGH (par défaut sur gemini-4-carbon-cyber-permissive).
• Mise en cache implicite avec mise en cache durable : la mise en cache implicite s'applique automatiquement aux préfixes de requêtes partagés de 4 096 jetons ou plus, la mise en cache durable étant activée par défaut. La mise en cache de contexte explicite n'est pas prise en charge.
• Entrées de fichiers Office et OpenDocument : en plus des fichiers PDF et en texte brut, 4 Carbon accepte les fichiers Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) et OpenDocument (.odt, .odp, .ods) intégrés ou provenant de Cloud Storage sur GenerateContent et l'API Interactions.
• Compréhension agentique des vidéos : la compréhension agentique des vidéos est en disponibilité générale et désactivée par défaut.

Guide de démarrage rapide

Avant de commencer, vous devez vous authentifier auprès de Gemini Enterprise Agent Platform à l'aide des identifiants par défaut de l'application (ADC) ou d'une clé API. Pour en savoir plus, consultez Premiers pas avec Agent Platform.

Dans les blocs de code suivants, remplacez PROJECT_ID par l'ID de votre projet.

Essayer dans Agent Studio

Pour tester des prompts et configurer gemini-4-carbon dans l'interface utilisateur d'Agent Studio, procédez comme suit :

1. Ouvrez Agent Studio dans votre projet Cloud de Confiance by S3NS et sélectionnez gemini-4-carbon sous le groupe Gemini.
2. Dans Paramètres du modèle, configurez les options suivantes :
   • Niveau de raisonnement : sélectionnez Low, Medium (par défaut) ou High.
   • Région : sélectionnez Global, us ou eu.
   • Limite de jetons de sortie : définissez une valeur comprise entre 32,768 et 1,048,576 (1,048,576 par défaut). Agent Studio gère automatiquement les jetons de continuation pour les réponses dépassant la limite d'une seule requête.

Installation

Passez à la dernière version du SDK Google Gen AI. La continuation automatique sur l'API Interactions nécessite google-genai >= 2.34.0 pour Python, @google/genai >= 2.32.0 pour JavaScript/TypeScript, >= 1.77.0 pour Go ou >= 1.80.0 pour Java (sur GenerateContent, la continuation automatique nécessite >= 2.30.1 pour Python, >= 2.29.1 pour JavaScript/TypeScript, >= 1.74.0 pour Go, >= 1.77.0 pour Java, >= 1.26.0 pour .NET ou >= 1.6.0 pour Kotlin) :

pip install --upgrade "google-genai>=2.34.0"

Requête de base

Envoyez une requête à gemini-4-carbon à l'aide du SDK Google Gen AI ou de REST :

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-4-carbon",
    contents="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(
            thinking_level="MEDIUM",  # Default: "MEDIUM" (Valid: "LOW", "MEDIUM", "HIGH")
        ),
    ),
)
print(response.text)

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

# Turn 1: Initial request (stored server-side by default)
turn1 = client.interactions.create(
    model="gemini-4-carbon",
    input="Design a lock-free ring buffer in Rust for multi-producer, single-consumer telemetry ingestion.",
    store=True,
)
print(turn1.output_text)

# Turn 2: Continue the conversation using previous_interaction_id
turn2 = client.interactions.create(
    model="gemini-4-carbon",
    input="Add a bounded backpressure policy and unit tests for concurrent writers.",
    previous_interaction_id=turn1.id,
)
print(turn2.output_text)

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-carbon:generateContent" \
-d '{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Provide an architectural review of this Go interface."
        }
      ]
    }
  ],
  "generationConfig": {
    "thinkingConfig": {
      "thinkingLevel": "MEDIUM"
    }
  }
}'

Sortie structurée

Pour générer une sortie JSON conforme à un schéma, configurez response_mime_type et response_schema :

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

class ArchitectureReview(BaseModel):
    component: str = Field(description="Service or module name")
    bottlenecks: list[str] = Field(description="Throughput or latency bottlenecks")
    recommended_changes: list[str] = Field(description="Concrete refactoring steps")

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

response = client.models.generate_content(
    model="gemini-4-carbon",
    contents="Review a synchronous order-processing pipeline backed by a single primary database at 15,000 writes/sec.",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=ArchitectureReview,
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    ),
)
print(response.text)

Exemples de décodage long

Par défaut, un seul segment d'API de premier plan génère jusqu'à 65 536 jetons de sortie lors du streaming ou 32 768 jetons de sortie lors d'une utilisation sans streaming, où la sortie inclut la réflexion, les appels de fonction et la réponse finale. Pour générer des complétions jusqu'à 1 048 576 jetons (moins vos jetons d'entrée), utilisez des décodages longs sur l'API Interactions ou GenerateContent. Pour en savoir plus sur les options de continuation, les transitions d'état et les règles de validation, consultez Décodages longs.

Utiliser des décodages longs avec l'API Interactions

Dans google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 et Java >= 1.80.0, interactions.create() suit automatiquement continuation_token entre les segments chaque fois qu'un segment renvoie status="requires_continuation". Vous pouvez également désactiver l'option (automatic_continuation=False) pour exécuter une boucle personnalisée stockée (store=True) ou sans état (store=False) :

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Automatic continuation is enabled by default in google-genai >= 2.34.0.
# Unary calls merge all segments into one Interaction with summed usage.
interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    generation_config={
        "max_output_tokens": 256000,
        "thinking_level": "high",
    },
)
print(interaction.output_text)
print(f"Merged segment IDs: {interaction.continuation_ids}")
print(f"Initial input tokens: {interaction.usage.initial_input_tokens}")

# Optional: Delete each stored server segment (last segment first) before its 7-day TTL expires.
for segment_id in reversed(interaction.continuation_ids or [interaction.id]):
    client.interactions.delete(id=segment_id)

# Streaming yields events across all segments in order. Intermediate segments
# emit interaction.completed with status="requires_continuation".
stream = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    stream=True,
    generation_config={
        "max_output_tokens": 256000,
        "thinking_level": "high",
    },
)
for event in stream:
    if event.event_type == "step.delta" and getattr(event.delta, "text", None):
        print(event.delta.text, end="", flush=True)
    elif (
        event.event_type == "interaction.completed"
        and event.interaction.status != "requires_continuation"
    ):
        print(f"\nFinal status: {event.interaction.status}")

# Set automatic_continuation=False to return after a single segment.
single_segment = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
    automatic_continuation=False,
)

from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

prompt = "Write a complete formal proof of the prime number theorem."

# Stored loop (store=True, default): chain previous_interaction_id + continuation_token
# without resending input.
segment = client.interactions.create(
    model="gemini-4-carbon",
    input=prompt,
    store=True,
    generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
    automatic_continuation=False,
)
full_text = segment.output_text or ""

while segment.status == "requires_continuation" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-carbon",
        previous_interaction_id=segment.id,
        continuation_token=segment.continuation_token,
        generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
        automatic_continuation=False,
    )
    full_text += segment.output_text or ""

# If status == "incomplete", max_output_tokens was exhausted; raise max_output_tokens
# to continue (leaving default automatic_continuation=True lets the SDK finish remaining segments).
if segment.status == "incomplete" and segment.continuation_token:
    segment = client.interactions.create(
        model="gemini-4-carbon",
        previous_interaction_id=segment.id,
        continuation_token=segment.continuation_token,
        generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
    )
    full_text += segment.output_text or ""

# Stateless loop (store=False): resend original input + continuation_token
# with no previous_interaction_id.
stateless_seg = client.interactions.create(
    model="gemini-4-carbon",
    input=prompt,
    store=False,
    generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
    automatic_continuation=False,
)
stateless_text = stateless_seg.output_text or ""
while stateless_seg.status == "requires_continuation" and stateless_seg.continuation_token:
    stateless_seg = client.interactions.create(
        model="gemini-4-carbon",
        input=prompt,
        store=False,
        continuation_token=stateless_seg.continuation_token,
        generation_config={"max_output_tokens": 131072, "thinking_level": "high"},
        automatic_continuation=False,
    )
    stateless_text += stateless_seg.output_text or ""

# Segment 1: Start a stored interaction (store=true by default)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 2: When status is "requires_continuation", pass previous_interaction_id
# and continuation_token without resending input
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "store": true,
    "previous_interaction_id": "SEGMENT_1_ID",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 1: Stateless interaction (store=false)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "store": false,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

# Segment 2: Resend the original input and continuation_token (no previous_interaction_id)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "store": false,
    "input": "Write a complete formal proof of the prime number theorem.",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 131072,
      "thinking_level": "high"
    }
  }'

Pour l'exécution asynchrone gérée par le serveur (background=True avec store=True) ou la récupération à partir de points de contrôle de streaming (événements interaction.status_update émis à 32 768 jetons de sortie, puis tous les 5 000 jetons), utilisez les modèles suivants :

import time
from google import genai

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# Start a server-managed background long decode (requires store=True)
interaction = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    background=True,
    store=True,
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)

while interaction.status in ("queued", "in_progress"):
    time.sleep(10)
    interaction = client.interactions.get(id=interaction.id)

print(f"Status: {interaction.status}")
print(interaction.output_text)

# Optional: Cancel an in-progress background interaction and resume later
# from its persisted checkpoint continuation_token (if >= 32,768 tokens decoded).
# cancelled = client.interactions.cancel(id=interaction.id)
# if cancelled.continuation_token:
#     resumed = client.interactions.create(
#         model="gemini-4-carbon",
#         previous_interaction_id=cancelled.id,
#         continuation_token=cancelled.continuation_token,
#         background=True,
#         generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
#     )

# Start a server-managed background long decode (requires store=true)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "background": true,
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

# Poll the interaction until status reaches completed, incomplete, failed, or cancelled
curl -s -X GET \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID"

# Optional: Cancel an in-progress background decode
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel"

# Optional: Resume a cancelled background decode from its checkpoint continuation_token
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "background": true,
    "store": true,
    "previous_interaction_id": "INTERACTION_ID",
    "continuation_token": "CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

from google import genai
from google.genai import errors

client = genai.Client(
    enterprise=True,
    project="PROJECT_ID",
    location="global",
)

# With default automatic_continuation=True, stream=True automatically
# reconnects from the latest interaction.status_update checkpoint (32,768
# output tokens, then every 5,000 tokens) if no output was yielded after the
# checkpoint. If a disconnect occurs after output was yielded since the last
# checkpoint, the SDK raises ContinuationInterruptedError so you can resume
# from err.continuation_token.
stream = client.interactions.create(
    model="gemini-4-carbon",
    input="Write a complete formal proof of the prime number theorem.",
    stream=True,
    store=True,
    generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
)

try:
    for event in stream:
        if event.event_type == "step.delta" and getattr(event.delta, "text", None):
            print(event.delta.text, end="", flush=True)
except errors.ContinuationInterruptedError as err:
    # Resuming from a mid-segment checkpoint regenerates any output yielded
    # after that checkpoint.
    if err.interaction_id and err.continuation_token:
        resumed_stream = client.interactions.create(
            model="gemini-4-carbon",
            previous_interaction_id=err.interaction_id,
            continuation_token=err.continuation_token,
            stream=True,
            store=True,
            generation_config={"max_output_tokens": 256000, "thinking_level": "high"},
        )
        for event in resumed_stream:
            if event.event_type == "step.delta" and getattr(event.delta, "text", None):
                print(event.delta.text, end="", flush=True)

# Start a streaming interaction; save interaction.id from interaction.created
# and the latest continuation_token from interaction.status_update SSE events
curl -N -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "stream": true,
    "store": true,
    "input": "Write a complete formal proof of the prime number theorem.",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

# Resume a dropped stream from the last saved checkpoint continuation_token
# (for store=false, resend the original input instead of previous_interaction_id)
curl -N -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/interactions" \
  -d '{
    "model": "gemini-4-carbon",
    "stream": true,
    "store": true,
    "previous_interaction_id": "SEGMENT_ID",
    "continuation_token": "CHECKPOINT_CONTINUATION_TOKEN",
    "generation_config": {
      "max_output_tokens": 256000,
      "thinking_level": "high"
    }
  }'

Utiliser des décodages longs avec GenerateContent

Sur GenerateContent (v1beta1), définissez max_output_tokens sur une valeur supérieure à 65 536 pour les requêtes de streaming ou supérieure à 32 768 pour les requêtes non liées au streaming (jusqu'à 1 048 576). Le SDK Google Gen AI suit automatiquement continuation_token sur les segments lorsque finish_reason est défini sur CONTINUATION (définissez automatic_continuation=False dans GenerateContentConfig pour désactiver cette option), ou vous pouvez transmettre continuation_token dans une boucle personnalisée :

from google import genai
from google.genai import types

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

# Automatic continuation is enabled by default in google-genai >= 2.30.1.
# Chunks across all continuation requests are yielded as a single stream.
for chunk in client.models.generate_content_stream(
    model="gemini-4-carbon",
    contents="Write a complete formal proof of the prime number theorem.",
    config=types.GenerateContentConfig(
        max_output_tokens=256000,
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
    ),
):
    print(chunk.text, end="")

# Set automatic_continuation=False to disable automatic continuation.
for chunk in client.models.generate_content_stream(
    model="gemini-4-carbon",
    contents="Write a complete formal proof of the prime number theorem.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="HIGH"),
        automatic_continuation=False,
    ),
):
    print(chunk.text, end="")

# Request 1: Initial request with maxOutputTokens > 32,768
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-carbon:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

# Request 2: Resend the original request with top-level continuationToken
# from Request 1 (candidates[0].continuationToken)
curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-4-carbon:generateContent" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Write a complete formal proof of the prime number theorem."}]
    }],
    "continuationToken": "CONTINUATION_TOKEN",
    "generationConfig": {
      "maxOutputTokens": 131072,
      "thinkingConfig": {"thinkingLevel": "HIGH"}
    }
  }'

Règles d'API et conventions de comportement obligatoires

4 Carbon applique les conventions des sections suivantes pour les niveaux de réflexion, les limites de jetons, la mise en cache, les paramètres de génération et l'exécution d'outils multitours.

Niveaux de raisonnement

4 Carbon accepte trois valeurs thinking_level (thinking_budget et MINIMAL renvoient une erreur de validation HTTP 400). Transmettez des valeurs en majuscules ("LOW", "MEDIUM", "HIGH") sur GenerateContent et des valeurs en minuscules ("low", "medium", "high") sur l'API Interactions. Le tableau suivant liste chaque niveau de réflexion et les charges de travail recommandées :

Limites de jetons, mise en cache et facturation

4 Carbon applique les règles suivantes concernant les jetons, la mise en cache, les contenus multimédias et la facturation :

• Limite unifiée de jetons d'entrée et de sortie et budgets de sortie par défaut : Les budgets de jetons et les limites de segment de premier plan fonctionnent comme suit :
  • La limite globale de jetons du modèle est de 1,048,576 jetons et inclut à la fois les jetons d'entrée et de sortie (où la sortie inclut le raisonnement, les appels de fonction et la réponse finale). max_output_tokens contrôle la limite de jetons de sortie pour la génération (jusqu'à 1,048,576 moins vos jetons d'entrée). Si vous définissez max_output_tokens sur une valeur supérieure à 1,048,576, une erreur HTTP 400 est renvoyée.
  • Lorsque max_output_tokens est omis dans GenerateContent ou l'API Interactions, le budget de sortie total par défaut (réflexion, appels de fonction et réponse) est de 65 536 jetons. Étant donné qu'un seul segment de premier plan génère jusqu'à 65 536 jetons lors du streaming ou 32 768 jetons en l'absence de streaming, le SDK Google Gen AI (v1beta1) enchaîne automatiquement deux segments de 32 768 jetons sur les appels sans streaming si nécessaire, tandis qu'une seule requête REST sans streaming s'arrête après un segment de premier plan de 32 768 jetons. Dans Agent Studio, la limite de jetons de sortie est définie par défaut sur 1,048,576 avec continuation automatique.
• Décodages longs : un seul segment de premier plan génère jusqu'à 65 536 jetons de sortie lors du streaming ou 32 768 jetons de sortie en l'absence de streaming. Pour étendre la sortie à un seul tour jusqu'à 1 048 576 jetons (moins les jetons d'entrée) sur l'API Interactions ou GenerateContent (v1beta1), consultez Décodages longs.
• Cache de contexte : le cache de contexte explicite n'est pas disponible. La mise en cache implicite (avec la mise en cache durable activée par défaut) s'applique automatiquement aux préfixes de requêtes partagés de 4 096 jetons ou plus. Placez donc le contenu statique au début de votre requête.
• Entrées Office et OpenDocument : transmettez des fichiers Word (application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.openxmlformats-officedocument.wordprocessingml.template, application/msword, application/vnd.oasis.opendocument.text), PowerPoint (application/vnd.openxmlformats-officedocument.presentationml.presentation, application/vnd.ms-powerpoint, application/vnd.oasis.opendocument.presentation) et des feuilles de calcul Excel ou OpenDocument (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet) de manière intégrée ou par URI Cloud Storage (gs://) à l'aide de inlineData ou fileData sur les entrées GenerateContent et document (y compris les résultats des outils) de l'API Interactions.
• Vidéo agentive : les vidéos importées sont définies par défaut sur media_processing="static". Définissez media_processing="agentic" pour activer le traitement agentique des vidéos.
• Comptage et facturation des jetons : chaque jeton traité par le modèle est comptabilisé et facturé, y compris les jetons de raisonnement, les instructions système des outils internes et les déclarations de fonction lors de l'utilisation de l'ancrage. L'ancrage avec la recherche Google reste également facturé par requête.

Paramètres, appel de fonction et validation du chat

4 Carbon applique les règles suivantes pour les paramètres de génération, les appels d'outils et l'historique des discussions :

• Paramètres d'échantillonnage ignorés (temperature, top_k, top_p) : le backend ignore les valeurs personnalisées. Contrôlez la profondeur du raisonnement avec thinking_level et le format de sortie avec response_schema.
• Paramètres non compatibles (frequency_penalty, presence_penalty et candidate_count supérieur à 1) : la transmission de frequency_penalty, presence_penalty ou candidate_count supérieur à 1 (candidateCount est fixé à 1) renvoie une erreur HTTP 400. Supprimez ces paramètres de vos requêtes.

• Appel de fonction : les déclarations d'outils et les tours d'exécution suivent ces règles :

  • Symétrie des tours : chaque FunctionResponse doit correspondre aux id, name et à l'ordre du FunctionCall précédent.
  • Exécution séquentielle : privilégiez l'exécution séquentielle des outils dans les boucles d'outils en plusieurs étapes.

  • Mise en forme avant l'outil : séparez les instructions intégrées par \n\n et évitez le texte non structuré avant les appels d'outils. Pour consigner l'état intermédiaire avant un appel d'outil, utilisez une déclaration de fonction dédiée :

    {
      "name": "update",
      "description": "Update working notes before tool execution",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "previous_step": {"type": "STRING"},
          "plan": {"type": "STRING"},
          "next_step": {"type": "STRING"}
        },
        "required": ["previous_step", "plan", "next_step"]
      }
    }
    

• Validation de la séquence de chat : les charges utiles de chat multitour appliquent les contraintes suivantes :

  • Les charges utiles de l'historique ne peuvent pas se terminer par un tour de rôle model.
  • Les tours de modèle préremplis ne sont pas acceptés.

Décodages longs

Le décodage long divise une génération de 1 048 576 jetons (moins vos jetons d'entrée) en plusieurs segments sur l'API Interactions ou GenerateContent (v1beta1). Sur l'API Interactions, chaque segment de premier plan génère jusqu'à 65 536 jetons de sortie lors du streaming (stream=true) ou 32 768 jetons de sortie lors du non-streaming (stream=false) et renvoie status="requires_continuation" avec un continuation_token chiffré. Vous pouvez également définir background=true (store=true) pour que le serveur exécute la boucle de continuation de manière asynchrone et stocke la sortie fusionnée dans un Interaction. Sur GenerateContent, les segments de streaming génèrent jusqu'à 65 536 jetons de sortie et les segments non-streaming génèrent jusqu'à 32 768 jetons de sortie avant d'émettre finish_reason=CONTINUATION avec continuation_token, jusqu'à finish_reason=STOP. Dans Agent Studio, si vous définissez la limite de jetons de sortie sur une valeur supérieure à 65 536 et inférieure ou égale à 1 048 576, les jetons de continuation sont gérés automatiquement. Pour obtenir des exemples de code exécutables, consultez les exemples du guide de démarrage rapide sur le décodage long.

Quand utiliser le décodage long

La plupart des requêtes se terminent dans la limite de sortie par défaut de 65 536 jetons (ou un seul segment de premier plan sans streaming de 32 768 jetons sur REST). N'utilisez le décodage long que lorsqu'une réponse nécessite plus de sortie que cela. Le décodage long donne au modèle plus de marge de manœuvre pour raisonner. Il ne rallonge pas les réponses (utilisez thinking_level pour contrôler la profondeur du raisonnement).

Choisir une option de continuation

Sélectionnez un modèle de continuation en fonction de la surface de votre API, de votre stratégie de stockage et de votre environnement d'exécution. Toutes les options du tableau suivant atteignent la même limite de 1 048 576 jetons (moins les jetons d'entrée) sur gemini-4-carbon et gemini-4-carbon-cyber-permissive.

Exigences concernant la version de l'API et du SDK

Les décodages longs nécessitent la version d'API et les versions minimales du SDK suivantes :

• Exigence de l'API v1beta1 (problème connu) : le décodage long (continuation_token) sur l'API Interactions et GenerateContent (generateContent et streamGenerateContent) n'est compatible qu'avec l'API v1beta1 (et non v1) sur Agent Platform. Le SDK Google Gen AI utilise v1beta1 par défaut, sauf si api_version='v1' est spécifié dans http_options (ou api_version="v1" sur interactions.create). Pour les appels REST directs, utilisez le chemin d'accès au point de terminaison /v1beta1/.
• Versions du SDK et compatibilité avec OpenAI : pour la continuation automatique sur l'API Interactions, passez à Python google-genai >= 2.34.0, JavaScript/TypeScript @google/genai >= 2.32.0, Go >= 1.77.0 ou Java >= 1.80.0 (pour les autres langages sur l'API Interactions, appelez l'API REST directement avec background=true ou une boucle de continuation personnalisée). Pour continuer automatiquement sur GenerateContent, passez à Python >= 2.30.1, JavaScript/TypeScript >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0 ou Kotlin >= 1.6.0. Les versions antérieures du SDK et la couche de compatibilité OpenAI ne peuvent pas récupérer les complétions longues à l'aide de jetons de continuation.

Règles de continuation de l'API Interactions

Les transitions d'état, les règles de chaînage et les comportements de stockage suivants s'appliquent aux décodages longs sur l'API Interactions.

Valeurs d'état et budget de jetons de sortie

Lorsque generation_config.max_output_tokens est omis dans une requête API Interactions, le budget de sortie total est défini par défaut sur 65 536 jetons (un appel sans streaming s'arrête donc à 32 768 jetons avec status="requires_continuation", et un deuxième segment peut générer les 32 768 jetons restants). Définissez generation_config.max_output_tokens sur une valeur maximale de 1,048,576 (moins les jetons d'entrée) pour des décodages plus longs dans les modes de premier plan et background=true. Le serveur renvoie les valeurs d'état suivantes :

• requires_continuation : la limite de sortie par segment (32 768 jetons pour les requêtes non diffusées en continu ou 65 536 jetons pour les requêtes diffusées en continu) a été atteinte avant max_output_tokens. Transmettez le continuation_token renvoyé lors de la requête suivante pour continuer le décodage.
• incomplete : le budget max_output_tokens total a été épuisé. Continuer avec continuation_token sans augmenter max_output_tokens renvoie une erreur HTTP 400 (max_output_tokens has already been exhausted). Augmentez max_output_tokens lors de la prochaine requête pour reprendre le décodage.
• completed : la génération s'est terminée naturellement et continuation_token est effacé.

Chaînage, changement de mode et stockage des segments

Les requêtes de continuation sur l'API Interactions appliquent les règles suivantes :

• Suite stockée (store=true, par défaut) : transmettez previous_interaction_id défini sur le segment id qui a émis le continuation_token avec continuation_token, et omettez input (le segment stocké contient déjà l'entrée du tour). Associez toujours chaque continuation_token au previous_interaction_id du segment qui l'a émis. Transmettre un continuation_token sur une interaction déjà completed renvoie une erreur HTTP 400.
• Continuation sans état (store=false) : omettez previous_interaction_id et renvoyez le input d'origine avec continuation_token sur chaque segment.
• Changer de mode store entre les segments : vous pouvez passer du mode stocké (store=true) au mode sans état (store=false) en cours de décodage en omettant previous_interaction_id et en renvoyant le input d'origine avec continuation_token. Le passage de l'état sans état (store=false) à l'état stocké (store=true) n'est pas possible, car il n'existe aucune interaction parente stockée pour previous_interaction_id.
• Changement de mode et branchement entre le premier plan et background=true : les continuations stockées (store=true) peuvent basculer entre l'exécution au premier plan (background=false) et en arrière-plan (background=true) entre les segments, y compris reprendre une interaction background=true annulée à partir de son point de contrôle continuation_token (conservé après 32 768 jetons de sortie) en mode arrière-plan ou premier plan. La réutilisation des mêmes valeurs previous_interaction_id et continuation_token crée des continuations ramifiées indépendantes.
• Application des limites de tour : démarrer un nouveau tour d'utilisateur (previous_interaction_id avec un nouveau input et sans continuation_token) à partir d'un segment dont l'état est requires_continuation ou incomplete renvoie une erreur HTTP 400. Terminez le décodage jusqu'à completed ou branchez votre prochain tour à partir de l'interaction completed la plus récente. Une fois que le dernier segment atteint completed, la transmission de l'élément id de ce dernier segment en tant que previous_interaction_id reconstruit l'historique complet de la conversation sur tous les segments précédents.
• Cohérence des paramètres entre les segments : la modification de model, system_instruction ou des déclarations de fonction (tools) sur un segment de continuation renvoie une erreur HTTP 400. Conservez également thinking_level et les outils intégrés inchangés d'un segment à l'autre (voir Problèmes connus).
• Comportement des segments uniques get, list et delete : en mode premier plan (background=false), chaque segment est stocké en tant que ressource Interaction distincte (interactions.get(id) ne renvoie que ce segment, interactions.list() liste chaque segment séparément et interactions.delete(id) ne supprime que ce segment ; lors de la suppression d'une chaîne de segments, supprimez-les dans l'ordre inverse, en commençant par le dernier segment). Dans le SDK Google Gen AI avec automatic_continuation=True (stream=False), interactions.create() fusionne tous les segments au retour et remplit interaction.continuation_ids avec les ID de segment ordonnés (se terminant par interaction.id). Si un segment ultérieur échoue, dépasse un timeout numérique par appel ou est supprimé en cours de flux après avoir dépassé un point de contrôle réactivable, le SDK génère ContinuationInterruptedError contenant partial_interaction, continuation_token, interaction_id et continuation_ids afin que vous puissiez reprendre à partir de continuation_token.

Règles de boucle personnalisées GenerateContent

Dans une boucle de continuation GenerateContent personnalisée, suivez ces règles :

• Définissez max_output_tokens sur une valeur supérieure à 65 536 (streaming) ou 32 768 (non-streaming) jusqu'à 1 048 576, puis renvoyez les valeurs d'origine de contents, system_instruction et tools à chaque requête de continuation, ainsi que la dernière valeur de continuation_token (un champ de premier niveau sur GenerateContentRequest dans REST ou dans GenerateContentConfig dans le SDK Google Gen AI).
• N'ajoutez pas de sortie de modèle partielle dans contents et n'envoyez pas de requête de suivi demandant au modèle de continuer.
• Continuez à boucler tant que finish_reason est CONTINUATION et que continuation_token est présent, même si un segment a utilisé l'intégralité des 32 768 ou 65 536 jetons pour la réflexion (parts: [{"text": ""}]). Si finish_reason est MAX_TOKENS lorsque continuation_token est présent, augmentez max_output_tokens dans la requête suivante.
• Combinez les parties accumulées en un seul tour model pour l'historique multitour uniquement après STOP.

Comptage, compactage et mise en cache implicite des jetons

La comptabilisation et la mise en cache des jetons sur les segments de continuation fonctionnent comme suit :

• Sur l'API Interactions, les appels interactions.create() sans streaming avec automatic_continuation=True et les interactions background=true gérées par le serveur additionnent le nombre de jetons de tous les segments dans usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens), en conservant le nombre de requêtes du premier segment dans usage.initial_input_tokens. Dans les boucles de premier plan personnalisées et les événements interaction.completed diffusés en streaming, le champ usage de chaque segment ne signale que le delta de ce segment. Par conséquent, additionnez les champs usage de tous les segments pour obtenir le nombre total de jetons facturés.
• Sur GenerateContent, le SDK Google Gen AI pour Python (generate_content et generate_content_stream) cumule le nombre total de jetons facturés sur les segments dans le usage_metadata final et conserve initial_prompt_token_count. Dans les boucles REST personnalisées, additionnez les valeurs finales de prompt_token_count, cached_content_token_count, candidates_token_count et thoughts_token_count pour tous les segments.
• Étant donné que chaque segment de continuation au premier plan remplit à nouveau la conversation et les jetons précédemment générés en tant qu'entrée, usage.total_input_tokens (sur l'API Interactions) et prompt_token_count (sur GenerateContent) augmentent d'un segment à l'autre. N'utilisez pas le nombre cumulé d'entrées pour déclencher la compression du contexte dans les harnais d'agent. Vérifiez plutôt usage.initial_input_tokens (ou initial_prompt_token_count sur GenerateContent) et ne compressez qu'une fois le tour terminé (status="completed" ou pas de continuation_token).
• Chaque segment de continuation préremplit à nouveau le prompt ainsi que les jetons précédemment décodés et est automatiquement éligible à la cache de contexte implicite (minimum de 4 096 jetons, avec mise en cache durable activée par défaut) lorsque les segments s'exécutent l'un après l'autre. Les segments terminés sont facturés à la fin de chaque segment, même si un segment ultérieur échoue ou est annulé.

Migrer de 3.1 Pro vers 4 Carbon

Le comportement suivant est différent de gemini-3.1-pro-preview :

• 4 Carbon a une limite unifiée de 1 048 576 jetons pour l'entrée et la sortie (où la sortie inclut le raisonnement, les appels de fonction et la réponse finale), au lieu de limites d'entrée et de sortie distinctes. Un seul segment de premier plan est limité à 65 536 jetons lors du streaming (ou 32 768 jetons en l'absence de streaming), et la sortie peut être étendue jusqu'à 1 048 576 jetons à l'aide de décodages longs sur l'API Interactions ou GenerateContent (géré automatiquement dans le SDK Google Gen AI, avec background=true sur l'API Interactions ou à l'aide de continuation_token dans des boucles personnalisées).
• thinking_budget renvoie une erreur HTTP 400 au lieu d'être mappé à un niveau de réflexion. MINIMAL renvoie également une erreur.
• La mise en cache explicite du contexte n'est pas compatible.
• Chaque jeton traité par le modèle est facturé, y compris les instructions système des outils internes et les déclarations de fonction lors de l'utilisation de l'ancrage.

Pour un comparatif, consultez Migrer depuis Gemini 3.1 Pro.

 client = genai.Client(
     enterprise=True,
     project="PROJECT_ID",
     location="global", # Supports "global", "us", and "eu" ("global" and "us" for cyber)
 )

 response = client.models.generate_content(
-    model="gemini-3.1-pro-preview",
+    model="gemini-4-carbon",
     contents=prompt,
     config=types.GenerateContentConfig(
-        temperature=0.0,
-        cached_content="projects/.../cachedContents/...", # Explicit caching unsupported
         thinking_config=types.ThinkingConfig(
-            thinking_budget=16384, # Returns HTTP 400 instead of mapping silently
-            thinking_level="MINIMAL", # MINIMAL unsupported on Gemini 4 Carbon
+            thinking_level="MEDIUM", # Valid: "LOW", "MEDIUM" (default), "HIGH"
         ),
     ),
 )

Pour migrer depuis gemini-3.1-pro-preview, procédez comme suit :

1. Remplacez l'ID du modèle par gemini-4-carbon (ou gemini-4-carbon-cyber-permissive pour les charges de travail de cybersécurité approuvées par le programme Fairwind).
2. Passez à la dernière version du SDK Google Gen AI et tenez compte de la limite unifiée de jetons d'entrée et de sortie : passez à google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 ou Java >= 1.80.0 pour la continuation automatique de l'API Interactions (ou >= 2.30.1 Python / >= 2.29.1 JavaScript sur GenerateContent). Les jetons d'entrée et de sortie (y compris le raisonnement et les appels de fonction) partagent la limite unifiée de 1 048 576 jetons. Pour les sorties dépassant 65 536 jetons (jusqu'à 1 048 576 jetons) sur l'API Interactions ou GenerateContent, définissez max_output_tokens sur une valeur supérieure à 65 536 afin que le SDK Google Gen AI continue automatiquement sur les segments (ou utilisez background=true ou une boucle continuation_token personnalisée).
3. Remplacez le paramètre de budget de raisonnement : remplacez thinking_budget et MINIMAL par thinking_level défini sur LOW, MEDIUM (par défaut sur gemini-4-carbon) ou HIGH (par défaut sur gemini-4-carbon-cyber-permissive) (utilisez "low", "medium" ou "high" en minuscules sur l'API Interactions).
4. Supprimez la mise en cache explicite et chargez à l'avance le contenu statique de la requête (4 096 jetons ou plus) pour une mise en cache implicite automatique.
5. Supprimez les paramètres qui n'ont aucun effet ou qui ne sont pas compatibles : supprimez les champs de génération ignorés et refusés comme suit :
   • Supprimez temperature, top_p et top_k, qui sont ignorés.
   • Supprimez frequency_penalty, presence_penalty et toute valeur candidate_count supérieure à 1.
   • Supprimez tous les tours de modèle préremplis des historiques de conversation.

Checklist récapitulative pour les développeurs

Utilisez la checklist suivante pour vérifier votre intégration 4 Carbon :

Problèmes connus

Les problèmes connus suivants s'appliquent aux décodages longs 4 Carbon :

• Les décodages longs nécessitent v1beta1 : le décodage long (continuation_token) sur l'API Interactions et l'API GenerateContent (generateContent et streamGenerateContent) n'est compatible qu'avec l'API v1beta1 (et non v1) sur Agent Platform. Le SDK Google Gen AI utilise v1beta1 par défaut, sauf si api_version='v1' est défini dans http_options (ou api_version="v1" sur interactions.create). Pour les appels REST directs, utilisez le chemin du point de terminaison /v1beta1/.
• Modifications des paramètres entre les segments de continuation de l'API Interactions : la modification de model, system_instruction ou des déclarations de fonction entre les segments de continuation renvoie une erreur HTTP 400, tandis que les modifications en cours de décodage de generation_config.thinking_level ou des outils intégrés (google_search, code_execution, url_context) ne sont pas rejetées par la validation du serveur. Conservez les thinking_level et les outils intégrés inchangés sur tous les segments d'une boucle de continuation.

Autres ressources

Pour en savoir plus sur 4 Carbon, consultez les ressources suivantes :

• Page du modèle Gemini 4 Carbon
• Premiers pas avec Gemini 4
• Notebook d'introduction
• Gemini 4 Carbon pour la cybersécurité