Guía para desarrolladores sobre Gemini 4 Carbon

Gemini 4 Carbon es el modelo de frontera de Google que se destaca en el trabajo profundo en tareas complejas del mundo real en dominios como la programación, las finanzas, el derecho, la ciberseguridad y la ciencia. Forma parte de la familia de Gemini 4. Gemini 4 Carbon es un modelo de frontera de Google sujeto al artículo 34 de las Condiciones Específicas del Servicio (para obtener más detalles, consulta Supervisión de abusos).

En este documento, se describen las funciones clave de 4 Carbon, las convenciones de la API que aplica, cómo migrar a ella y una guía de inicio rápido. Para obtener una descripción general de la familia Gemini 4, consulta Comienza a usar Gemini 4.

Funciones clave de Gemini 4 Carbon

Gemini 4 Carbon incluye las siguientes funciones:

• Límite unificado de tokens de entrada y salida: 4 Carbon tiene un límite unificado de 1,048,576 tokens que incluye los tokens de entrada y salida (donde la salida incluye el razonamiento, las llamadas a funciones y la respuesta final).
• Decodificaciones largas de hasta 1,048,576 tokens: 4 Carbon extiende la generación más allá de un solo segmento en primer plano (65,536 tokens cuando se transmite o 32,768 tokens cuando no se transmite) hasta 1,048,576 tokens (menos tus tokens de entrada) tanto en la API de Interactions como en GenerateContent (v1beta1). El SDK de IA generativa de Google controla continuation_token automáticamente en todos los segmentos, o puedes ejecutar decodificaciones en segundo plano asíncronas administradas por el servidor (background=true) o administrar continuation_token en un bucle de continuación personalizado.
• Niveles de pensamiento: 4 Carbon admite LOW, MEDIUM (predeterminado en gemini-4-carbon) y HIGH (predeterminado en gemini-4-carbon-cyber-permissive).
• Almacenamiento en caché implícito con almacenamiento en caché duradero: El almacenamiento en caché implícito se aplica automáticamente a los prefijos de instrucciones compartidos de 4,096 tokens o más, con el almacenamiento en caché duradero habilitado de forma predeterminada. No se admite el almacenamiento en caché de contexto explícito.
• Entradas de archivos de Office y OpenDocument: Además de PDF y texto sin formato, 4 Carbon acepta archivos de Microsoft Office (.docx, .dotx, .doc, .pptx, .ppt, .xlsx, .xls) y OpenDocument (.odt, .odp, .ods) intercalados o de Cloud Storage en GenerateContent y la API de Interactions.
• Comprensión de video de agentes: La comprensión de video de agentes está disponible de forma general y está desactivada de forma predeterminada.

Guía de inicio rápido

Antes de comenzar, debes autenticarte en Gemini Enterprise Agent Platform con las credenciales predeterminadas de la aplicación (ADC) o una clave de API. Consulta Comienza a usar Agent Platform para obtener más información.

En los siguientes bloques de código, reemplaza PROJECT_ID por el ID de tu proyecto.

Probar en Agent Studio

Para probar instrucciones y configurar gemini-4-carbon en la IU de Agent Studio, haz lo siguiente:

1. Abre Agent Studio en tu proyecto de Cloud de Confiance by S3NS y selecciona gemini-4-carbon en el grupo de Gemini.
2. En Configuración del modelo, establece las siguientes opciones:
   • Nivel de pensamiento: Elige Low, Medium (predeterminado) o High.
   • Región: Selecciona Global, us o eu.
   • Límite de tokens de salida: Se establece entre 32,768 y 1,048,576 (1,048,576 es el valor predeterminado). Agent Studio controla los tokens de continuación automáticamente para las respuestas que superan el límite de una sola solicitud.

Instalación

Actualiza al SDK de IA generativa de Google más reciente. La continuación automática en la API de Interactions requiere google-genai >= 2.34.0 para Python, @google/genai >= 2.32.0 para JavaScript/TypeScript, >= 1.77.0 para Go o >= 1.80.0 para Java (en GenerateContent, la continuación automática requiere >= 2.30.1 para Python, >= 2.29.1 para JavaScript/TypeScript, >= 1.74.0 para Go, >= 1.77.0 para Java, >= 1.26.0 para .NET o >= 1.6.0 para Kotlin):

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

Solicitud básica

Envía una solicitud a gemini-4-carbon con el SDK de IA generativa de Google o 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"
    }
  }
}'

Resultados estructurados

Para generar un resultado JSON que se ajuste a un esquema, configura response_mime_type y 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)

Ejemplos de decodificación larga

De forma predeterminada, un solo segmento de la API en primer plano genera hasta 65,536 tokens de salida cuando se transmite o 32,768 tokens de salida cuando no se transmite, donde el resultado incluye el razonamiento, las llamadas a funciones y la respuesta final. Para generar finalizaciones de hasta 1,048,576 tokens (menos los tokens de entrada), usa decodificaciones largas en la API de Interactions o GenerateContent. Para conocer las opciones de continuación, las transiciones de estado y las reglas de validación, consulta Decodificaciones largas.

Usa decodificaciones largas con la API de Interactions

En google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 y Java >= 1.80.0, interactions.create() sigue automáticamente a continuation_token en todos los segmentos cada vez que un segmento devuelve status="requires_continuation". También puedes inhabilitar (automatic_continuation=False) para ejecutar un bucle personalizado almacenado (store=True) o sin estado (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"
    }
  }'

Para la ejecución asíncrona administrada por el servidor (background=True con store=True) o la recuperación de puntos de control de transmisión (eventos interaction.status_update emitidos en 32,768 tokens de salida y cada 5,000 tokens a partir de ese momento), usa los siguientes patrones:

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

Usa decodificaciones largas con GenerateContent

En GenerateContent (v1beta1), establece max_output_tokens en un valor superior a 65,536 para las solicitudes de transmisión o superior a 32,768 para las solicitudes que no son de transmisión (hasta 1,048,576). El SDK de IA generativa de Google sigue automáticamente continuation_token en todos los segmentos cuando finish_reason es CONTINUATION (establece automatic_continuation=False en GenerateContentConfig para inhabilitar esta opción) o puedes pasar continuation_token en un bucle personalizado:

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

Reglas de API y convenciones de comportamiento obligatorias

4 Carbon aplica las convenciones de las siguientes secciones para los niveles de pensamiento, los límites de tokens, el almacenamiento en caché, los parámetros de generación y la ejecución de herramientas de varios turnos.

Niveles de razonamiento

4 Carbon admite tres valores de thinking_level (thinking_budget y MINIMAL devuelven un error de validación HTTP 400). Pasa valores en mayúsculas ("LOW", "MEDIUM", "HIGH") en GenerateContent y valores en minúsculas ("low", "medium", "high") en la API de Interactions. En la siguiente tabla, se enumeran cada nivel de pensamiento y sus cargas de trabajo recomendadas:

Límites de tokens, almacenamiento en caché y facturación

4 Carbon aplica las siguientes reglas de token, almacenamiento en caché, contenido multimedia y facturación:

• Límite unificado de tokens de entrada y salida, y presupuestos de salida predeterminados: Los presupuestos de tokens y los límites de segmentos en primer plano funcionan de la siguiente manera:
  • El límite general de tokens del modelo es de 1,048,576 tokens y, además, incluye los tokens de entrada y salida (en los que la salida incluye el razonamiento, las llamadas a funciones y la respuesta final). max_output_tokens controla el límite de tokens de salida para la generación (hasta 1,048,576 menos tus tokens de entrada). Si configuras max_output_tokens con un valor mayor que 1,048,576, se devuelve un error HTTP 400.
  • Cuando se omite max_output_tokens en GenerateContent o la API de Interactions, el presupuesto de salida total predeterminado (razonamiento, llamadas a funciones y respuesta) es de 65,536 tokens. Debido a que un solo segmento en primer plano genera hasta 65,536 tokens cuando se transmite o 32,768 tokens cuando no se transmite, el SDK de IA generativa de Google (v1beta1) encadena automáticamente dos segmentos de 32,768 tokens en llamadas que no son de transmisión cuando es necesario, mientras que una sola solicitud de REST que no es de transmisión se detiene después de un segmento en primer plano de 32,768 tokens. En Agent Studio, el límite de tokens de salida se establece de forma predeterminada en 1,048,576 con continuación automática.
• Decodificaciones largas: Un solo segmento en primer plano genera hasta 65,536 tokens de salida cuando se transmite o 32,768 tokens de salida cuando no se transmite. Para extender el resultado de un solo turno hasta 1,048,576 tokens (menos los tokens de entrada) en la API de Interactions o GenerateContent (v1beta1), consulta Decodificaciones largas.
• Almacenamiento en caché de contexto: No se admite el almacenamiento en caché de contexto explícito. El almacenamiento en caché implícito (con el almacenamiento en caché duradero habilitado de forma predeterminada) se aplica automáticamente a los prefijos de instrucciones compartidos de 4,096 tokens o más, por lo que debes colocar el contenido estático al principio de la instrucción.
• Entradas de Office y OpenDocument: Pasa archivos de 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) y hojas de cálculo de Excel o OpenDocument (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-excel, application/vnd.oasis.opendocument.spreadsheet) de forma intercalada o por URI de Cloud Storage (gs://) con inlineData o fileData en las entradas GenerateContent y document (incluidos los resultados de las herramientas) en la API de Interactions.
• Video de agente: Los videos subidos se establecen de forma predeterminada en media_processing="static". Establece media_processing="agentic" para habilitar el procesamiento de video agéntico.
• Recuento de tokens y facturación: Cada token que procesa el modelo se cuenta y se factura, incluidos los tokens de razonamiento y las instrucciones internas del sistema de herramientas y las declaraciones de funciones cuando se usa la fundamentación. La fundamentación con la Búsqueda de Google también se sigue facturando por consulta.

Parámetros, llamada a funciones y validación de chat

4 Carbon aplica las siguientes reglas para los parámetros de generación, las llamadas a la herramienta y el historial de chat:

• Parámetros de muestreo ignorados (temperature, top_k, top_p): El backend ignora los valores personalizados. Controla la profundidad del razonamiento con thinking_level y el formato de salida con response_schema.
• Parámetros no admitidos (frequency_penalty, presence_penalty y candidate_count mayores que 1): Pasar frequency_penalty, presence_penalty o candidate_count mayores que 1 (candidateCount se fija en 1) devuelve un error de HTTP 400. Quita estos parámetros de tus solicitudes.

• Llamada a función: Las declaraciones de herramientas y los turnos de ejecución siguen estas reglas:

  • Simetría de giro: Cada FunctionResponse debe coincidir con el id, name y el orden del FunctionCall anterior.
  • Ejecución secuencial: Prefiere los turnos de ejecución secuencial de herramientas en bucles de herramientas de varios pasos.

  • Formato previo a la herramienta: Separa las instrucciones intercaladas con \n\n y evita el texto no estructurado antes de las llamadas a la herramienta. Para registrar el estado intermedio antes de una llamada a la herramienta, usa una declaración de función dedicada:

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

• Validación de la secuencia de chat: Las cargas útiles de chat de varios turnos aplican las siguientes restricciones:

  • Las cargas útiles del historial no pueden terminar con un turno de rol model.
  • No se admiten las respuestas predefinidas del modelo.

Decodificaciones largas

La decodificación larga divide una generación de hasta 1,048,576 tokens (menos tus tokens de entrada) en varios segmentos en la API de Interactions o GenerateContent (v1beta1). En la API de Interactions, cada segmento en primer plano genera hasta 65,536 tokens de salida cuando se transmite (stream=true) o 32,768 tokens de salida cuando no se transmite (stream=false) y devuelve status="requires_continuation" con un continuation_token encriptado, o puedes establecer background=true (store=true) para que el servidor ejecute el bucle de continuación de forma asíncrona y almacene el resultado combinado en un Interaction. En GenerateContent, los segmentos de transmisión generan hasta 65,536 tokens de salida y los segmentos que no son de transmisión generan hasta 32,768 tokens de salida antes de emitir finish_reason=CONTINUATION con continuation_token, lo que continúa hasta finish_reason=STOP. En Agent Studio, establecer el límite de tokens de salida en un valor superior a 65,536 y hasta 1,048,576 controla los tokens de continuación automáticamente. Para obtener muestras de código ejecutables, consulta los ejemplos de la guía de inicio rápido de decodificación larga.

Cuándo usar la decodificación larga

La mayoría de las solicitudes finalizan dentro del presupuesto de salida predeterminado de 65,536 tokens (o un solo segmento en primer plano sin transmisión de 32,768 tokens a través de REST). Usa la decodificación larga solo cuando una respuesta necesite más resultados que eso. La decodificación larga le da al modelo más espacio para razonar; no hace que las respuestas sean más largas (usa thinking_level para controlar la profundidad del razonamiento).

Elige una opción de continuación

Selecciona un patrón de continuación según la plataforma de la API, la postura de almacenamiento y el entorno de ejecución. Todas las opciones de la siguiente tabla alcanzan el mismo límite de 1,048,576 tokens (menos los tokens de entrada) en gemini-4-carbon y gemini-4-carbon-cyber-permissive.

Requisitos de la versión de la API y del SDK

Las decodificaciones largas requieren la siguiente versión de la API y las versiones mínimas del SDK:

• Requisito de la API de v1beta1 (problema conocido): La decodificación larga (continuation_token) tanto en la API de Interactions como en GenerateContent (generateContent y streamGenerateContent) solo se admite en la API de v1beta1 (no en v1) en Agent Platform. El SDK de IA generativa de Google usa v1beta1 de forma predeterminada, a menos que se especifique api_version='v1' en http_options (o api_version="v1" en interactions.create). Para las llamadas de REST directas, usa la ruta del extremo /v1beta1/.
• Versiones del SDK y compatibilidad con OpenAI: Para la continuación automática en la API de Interactions, actualiza a Python google-genai >= 2.34.0, JavaScript/TypeScript @google/genai >= 2.32.0, Go >= 1.77.0 o Java >= 1.80.0 (para otros lenguajes en la API de Interactions, llama a la API de REST directamente con background=true o un bucle de continuación personalizado). Para continuar automáticamente en GenerateContent, actualiza a Python >= 2.30.1, JavaScript/TypeScript >= 2.29.1, Go >= 1.74.0, Java >= 1.77.0, .NET >= 1.26.0 o Kotlin >= 1.6.0. Las versiones anteriores del SDK y la capa de compatibilidad con OpenAI no pueden recuperar respuestas largas con tokens de continuación.

Reglas de continuación de la API de Interactions

Las siguientes transiciones de estado, reglas de encadenamiento y comportamientos de almacenamiento se aplican a las decodificaciones largas en la API de Interactions.

Valores de estado y presupuesto de tokens de salida

Cuando se omite generation_config.max_output_tokens en una solicitud a la API de Interactions, el presupuesto de salida total se establece de forma predeterminada en 65,536 tokens (por lo que una llamada que no es de transmisión se detiene en 32,768 tokens con status="requires_continuation", y un segundo segmento puede generar los 32,768 tokens restantes). Configura generation_config.max_output_tokens hasta 1,048,576 (menos tokens de entrada) para decodificaciones más largas en los modos en primer plano y background=true. El servidor devuelve los siguientes valores de estado:

• requires_continuation: Se alcanzó el límite de salida por segmento (32,768 sin transmisión o 65,536 con transmisión) antes de max_output_tokens. Pasa el continuation_token devuelto en la siguiente solicitud para continuar con la decodificación.
• incomplete: Se agotó el presupuesto total de max_output_tokens. Si continúas con continuation_token sin aumentar max_output_tokens, se muestra un error HTTP 400 (max_output_tokens has already been exhausted). Aumenta max_output_tokens en la siguiente solicitud para reanudar la decodificación.
• completed: La generación finalizó de forma natural y se borra continuation_token.

Encadenamiento, cambio de modo y almacenamiento de segmentos

Las solicitudes de continuación en la API de Interactions aplican las siguientes reglas:

• Continuación almacenada (store=true, predeterminada): Pasa previous_interaction_id configurado en el segmento id que emitió el continuation_token junto con continuation_token y omite input (el segmento almacenado ya contiene la entrada de turno). Siempre vincula cada continuation_token con el previous_interaction_id del segmento que lo emitió. Si pasas un continuation_token en una interacción que ya se completed, se devuelve un error de HTTP 400.
• Continuación sin estado (store=false): Omite previous_interaction_id y vuelve a enviar el input original junto con continuation_token en cada segmento.
• Cambia los modos de store en los segmentos: Puedes cambiar de almacenado (store=true) a sin estado (store=false) a mitad de la decodificación omitiendo previous_interaction_id y volviendo a enviar el input original con continuation_token. No se admite el cambio de sin estado (store=false) a almacenado (store=true) porque no existe una interacción superior almacenada para previous_interaction_id.
• Cambio y ramificación de modo en primer plano y background=true: Las continuaciones almacenadas (store=true) pueden cambiar entre la ejecución en primer plano (background=false) y en segundo plano (background=true) en todos los segmentos, lo que incluye reanudar una interacción background=true cancelada desde su punto de control continuation_token (que se conserva después de 32,768 tokens de salida) en modo en segundo plano o en primer plano. Si vuelves a usar los mismos valores de previous_interaction_id y continuation_token, se crearán continuaciones ramificadas independientes.
• Aplicación de límites de turnos: Iniciar un nuevo turno de usuario (previous_interaction_id con un input nuevo y sin continuation_token) desde un segmento cuyo estado es requires_continuation o incomplete devuelve un error HTTP 400. Termina de continuar la decodificación a completed o ramifica tu próximo turno desde la interacción completed más reciente. Una vez que el segmento final alcance completed, pasar el id de ese segmento final como previous_interaction_id reconstruirá el historial de conversación completo en todos los segmentos anteriores.
• Coherencia de los parámetros en los segmentos: Si cambias model, system_instruction o las declaraciones de funciones (tools) en un segmento de continuación, se muestra un error de HTTP 400. Mantén thinking_level y las herramientas integradas sin cambios en los segmentos (consulta Problemas conocidos).
• Comportamiento de un solo segmento de get, list y delete: En el modo en primer plano (background=false), cada segmento se almacena como un recurso Interaction independiente (interactions.get(id) muestra solo ese segmento, interactions.list() enumera cada segmento por separado y interactions.delete(id) borra solo ese segmento; cuando borres una cadena de segmentos, hazlo en orden inverso, desde el último segmento hacia atrás). En el SDK de IA generativa de Google con automatic_continuation=True (stream=False), interactions.create() combina todos los segmentos en la devolución y propaga interaction.continuation_ids con los IDs de segmento ordenados (que terminan con interaction.id). Si un segmento posterior falla, excede un timeout numérico por llamada o se interrumpe a mitad de la transmisión después de que se avanzó más allá de un punto de control reanudable, el SDK genera ContinuationInterruptedError con partial_interaction, continuation_token, interaction_id y continuation_ids para que puedas reanudar desde continuation_token.

Reglas de bucle personalizado de GenerateContent

En un bucle de continuación personalizado de GenerateContent, sigue estas reglas:

• Establece max_output_tokens en un valor superior a 65,536 (transmisión) o 32,768 (sin transmisión) hasta 1,048,576, y vuelve a enviar los valores originales de contents, system_instruction y tools en cada solicitud de continuación junto con el valor más reciente de continuation_token (un campo de nivel superior en GenerateContentRequest en REST o en GenerateContentConfig en el SDK de IA generativa de Google).
• No agregues el resultado parcial del modelo a contents ni envíes una instrucción de seguimiento para pedirle al modelo que continúe.
• Sigue repitiendo el bucle mientras finish_reason sea CONTINUATION y continuation_token esté presente, incluso si un segmento usó los 32,768 o 65,536 tokens en el pensamiento (parts: [{"text": ""}]). Si finish_reason es MAX_TOKENS cuando continuation_token está presente, aumenta max_output_tokens en la siguiente solicitud.
• Combina las partes acumuladas en un solo turno de model para el historial de varios turnos solo después de STOP.

Recuento de tokens, compactación y almacenamiento en caché implícito

La contabilización y el almacenamiento en caché de tokens en los segmentos de continuación funcionan de la siguiente manera:

• En la API de Interactions, las llamadas interactions.create() sin transmisión con automatic_continuation=True y las interacciones background=true administradas por el servidor suman los recuentos de tokens en todos los segmentos de usage (total_input_tokens, total_cached_tokens, total_output_tokens, total_thought_tokens, total_tokens), lo que conserva el recuento de instrucciones del primer segmento en usage.initial_input_tokens. En los bucles personalizados en primer plano y los eventos de interaction.completed transmitidos, el usage de cada segmento informa solo el delta de ese segmento, por lo que se deben sumar los campos usage de todos los segmentos para obtener el total de tokens facturados.
• En GenerateContent, el SDK de IA generativa de Google para Python (generate_content y generate_content_stream) acumula el total de tokens facturados en los segmentos del usage_metadata final y conserva initial_prompt_token_count. En los bucles de REST personalizados, suma los valores finales de prompt_token_count, cached_content_token_count, candidates_token_count y thoughts_token_count en todos los segmentos.
• Debido a que cada segmento de continuación en primer plano vuelve a completar previamente la conversación y los tokens generados anteriormente como entrada, usage.total_input_tokens (en la API de Interactions) y prompt_token_count (en GenerateContent) aumentan en todos los segmentos. No uses recuentos de entradas acumulativos para activar la compactación de contexto en los arneses de agentes. En su lugar, verifica usage.initial_input_tokens (o initial_prompt_token_count en GenerateContent) y compacta solo después de que finalice el turno (status="completed" o sin continuation_token).
• Cada segmento de continuación vuelve a completar previamente la instrucción y los tokens decodificados con anterioridad, y califica automáticamente para el almacenamiento en caché de contexto implícito (mínimo de 4,096 tokens, con el almacenamiento en caché duradero habilitado de forma predeterminada) cuando los segmentos se ejecutan de forma consecutiva. Los segmentos completados se facturan al final de cada segmento, incluso si un segmento posterior falla o se cancela.

Migra de 3.1 Pro a 4 Carbon

El siguiente comportamiento es diferente del de gemini-3.1-pro-preview:

• 4 Carbon tiene un límite unificado de 1,048,576 tokens para la entrada y la salida (donde la salida incluye el razonamiento, las llamadas a funciones y la respuesta final), en lugar de límites de entrada y salida separados. Un solo segmento en primer plano tiene un límite de 65,536 tokens cuando se transmite (o 32,768 tokens cuando no se transmite), y el resultado se puede extender hasta 1,048,576 tokens con decodificaciones largas en la API de Interactions o GenerateContent (se controla automáticamente en el SDK de IA generativa de Google, con background=true en la API de Interactions o con continuation_token en bucles personalizados).
• thinking_budget devuelve un error de HTTP 400 en lugar de asignarse a un nivel de pensamiento. MINIMAL también devuelve un error.
• No se admite el almacenamiento en caché de contexto explícito.
• Se factura cada token que procesa el modelo, incluidas las instrucciones internas del sistema de herramientas y las declaraciones de funciones cuando se usa la fundamentación.

Para obtener una comparación en paralelo, consulta Migra desde 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"
         ),
     ),
 )

Para migrar desde gemini-3.1-pro-preview, haz lo siguiente:

1. Actualiza el ID del modelo a gemini-4-carbon (o gemini-4-carbon-cyber-permissive para las cargas de trabajo de ciberseguridad aprobadas a través del Fairwind Program).
2. Actualiza al SDK de IA generativa de Google más reciente y ten en cuenta el límite unificado de tokens de entrada y salida: Actualiza a google-genai >= 2.34.0 (Python), @google/genai >= 2.32.0 (JavaScript/TypeScript), Go >= 1.77.0 o Java >= 1.80.0 para la continuación automática de la API de Interactions (o >= 2.30.1 Python/>= 2.29.1 JavaScript en GenerateContent). Los tokens de entrada y salida (incluidos los de razonamiento y las llamadas a funciones) comparten el límite unificado de 1,048,576 tokens. Para los resultados que superen los 65,536 tokens (hasta 1,048,576 tokens) en la API de Interactions o GenerateContent, establece max_output_tokens en un valor superior a 65,536 para que el SDK de IA generativa de Google continúe automáticamente en los segmentos (o usa background=true o un bucle continuation_token personalizado).
3. Reemplaza el parámetro de presupuesto de razonamiento: Reemplaza thinking_budget y MINIMAL por thinking_level establecido en LOW, MEDIUM (predeterminado en gemini-4-carbon) o HIGH (predeterminado en gemini-4-carbon-cyber-permissive) (usa minúsculas "low", "medium" o "high" en la API de Interactions).
4. Quita el almacenamiento en caché explícito y carga previamente el contenido de instrucciones estático (4,096 tokens o más) para el almacenamiento en caché implícito automático.
5. Quita los parámetros que no tienen efecto o no son compatibles: Quita los campos de generación ignorados y rechazados de la siguiente manera:
   • Quita temperature, top_p y top_k, que se ignoran.
   • Quita frequency_penalty, presence_penalty y cualquier valor de candidate_count mayor que 1.
   • Quita las respuestas predefinidas del modelo de los historiales de conversaciones.

Lista de tareas de resumen para desarrolladores

Usa la siguiente lista de tareas para verificar tu integración de 4 Carbon:

Problemas conocidos

Los siguientes problemas conocidos se aplican a las decodificaciones largas de 4 Carbon:

• La decodificación de contenido largo requiere v1beta1: La decodificación de contenido largo (continuation_token) en la API de Interactions y la API de GenerateContent (generateContent y streamGenerateContent) solo se admite en la API de v1beta1 (no en v1) en Agent Platform. El SDK de IA generativa de Google usa v1beta1 de forma predeterminada, a menos que se establezca api_version='v1' en http_options (o api_version="v1" en interactions.create). Para las llamadas de REST directas, usa la ruta del extremo /v1beta1/.
• Cambios de parámetros en los segmentos de continuación de la API de Interactions: Cambiar model, system_instruction o las declaraciones de funciones en los segmentos de continuación devuelve un error de HTTP 400, mientras que los cambios a mitad de la decodificación en generation_config.thinking_level o las herramientas integradas (google_search, code_execution, url_context) no se rechazan por la validación del servidor. Mantén thinking_level y las herramientas integradas sin cambios en todos los segmentos de un bucle de continuación.

Recursos adicionales

Para obtener más información sobre 4 Carbon, consulta los siguientes recursos:

• Página del modelo Gemini 4 Carbon
• Comienza a usar Gemini 4
• Notebook de introducción
• Gemini 4 Carbon para la seguridad cibernética