Long outputs from Carbon should use background execution through the Interactions API or client-side continuation. In background mode, the server continues generation and returns the complete interaction. In client-side mode, you need to handle segments, status, recovery after disconnection, and the token budget correctly.
Suitable tasks: Complex math, science, research, proof, or advanced coding tasks that genuinely require a single interaction to exceed 65,536 thinking and output tokens, and evaluation tasks that are prone to truncation at the output limit.
Unsuitable tasks: Chat, Q&A, summarization, classification, information extraction, short tool calls in multi-turn agents, latency-sensitive requests, or requests whose input is already close to the context limit.
Supported model version: Gemini 4 Carbon, gemini-4-carbon.
Supported clients, agents, or APIs: Gemini API Interactions API, background execution, or the Google GenAI SDK with automatic continuation support. Foreground automatic continuation for Carbon requires Python SDK 2.34.0+, JavaScript 2.32.0+, Go 1.77.0+, Java 1.80.0+, or .NET 1.28.0+.
Recommended reasoning level and parameters: Set max_output_tokens > 65,536 only when long output is truly needed. The official example uses 262,144 and thinking_level="high". medium is sufficient by default for most coding and agent tasks. The total limit is no greater than 1,048,576 - input tokens.
The following Python configuration is adapted from the official example and preserves its SDK call, background polling, and text concatenation across segments. The input is an editorial placeholder that should be replaced with the actual task. It can be run after installing and initializing the official google-genai SDK:
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-carbon",
input="替换为确实需要长输出的任务",
background=True,
generation_config={
"max_output_tokens": 262144,
"thinking_level": "high",
},
)
while interaction.status in ("in_progress", "queued"):
time.sleep(5)
interaction = client.interactions.get(id=interaction.id)
text = "".join(
content.text
for step in interaction.steps
if step.type == "model_output"
for content in step.content
if content.type == "text"
)
print(text)
print("Status:", interaction.status)
print("Usage:", interaction.usage)Confirm that the task truly requires more than the default single-response limit. Most requests finish within 65,536 tokens.
Set background=True in the request and set max_output_tokens to more than 65,536. Once the background interaction returns in_progress, continue polling while its status is queued or in_progress.
After the interaction ends, check the final status, then read the text and usage. Background results combine all hops. If processing steps yourself, concatenate only the text in model_output.
To stop a running interaction, call client.interactions.cancel(id=interaction.id). Work already completed is still billed.
If using foreground automatic continuation, keep the combined result returned by interactions.create. The SDK's interactions.get returns only the last hop. For a follow-up, use the ID of the final hop as previous_interaction_id.
The default output limit is a total of 65,536 thinking and output tokens. Long decode splits generation into consecutive hops: each background segment can contain up to 65,536 tokens, while a single non-streaming foreground segment for Carbon can contain up to 32,768 tokens. SDKs with automatic continuation enabled make subsequent calls on the caller's behalf.
In background mode, set max_output_tokens above 65,536. The server continues generation until the model finishes or reaches the limit. A background interaction can run for up to 24 hours.
Foreground automatic continuation applies to requests that exceed the single-segment limit. Older SDK versions do not continue automatically. If a hop is interrupted, the SDK may raise ContinuationInterruptedError, whose partial_interaction contains the completed portion. To resume, provide the interaction ID and continuation_token. If store=false, resend the input.
max_output_tokens is a shared budget for thinking and visible output across the entire interaction. Lowering the limit only causes earlier truncation. It does not make thinking more concise. To reduce token use, lower thinking_level.
Tokens from all hops are billed, including segments that contain only thinking. interaction.usage provides counts for input, cached input, output, thinking, and total tokens. With multiple segments, input is counted again for each hop, so total_input_tokens does not equal the actual context size.
Input, thinking, and output share a 1,048,576-token context window. The available output budget is also limited by the space used by the input.
Raising max_output_tokens only increases the available budget. It does not guarantee that the model will write to that length. The official documentation explicitly says the model does not follow word-count or token-length targets.
Long decode may take several minutes. For a long-running stream, save the interaction ID and each event's event_id. After disconnection, resume reading from the last event_id and wait until the stream ends before checking the status. Do not mistake completion of an intermediate hop for completion of the whole interaction.
Canceled or failed interactions are still billed for work already completed. total_input_tokens includes repeated input and cannot be used directly to decide whether the context should be compressed.
Collected on 2026-11-16. The body of Google's Long decode documentation was read through Tabbit, including its visible code example, status explanations, and budget explanations. The Gemini API was not called. The code is a runnable configuration adapted from the official background example. Its input text is a placeholder, and actual model output was not verified.
Gemini 4 Carbon