> ## AI Agent Context
> - Full documentation index: https://aistudio.google.com/llms.txt
> - Gemini Docs MCP server (consistent live info): https://gemini-api-docs-mcp.dev
> - Coding agent skills & setup guide: https://aistudio.google.com/docs/coding-agents.md

# Long decode

{% callout type="note" %}
  We recommend the Interactions API for new projects. On the Interactions API, our servers run long decode for you with background execution. See [long decode with the Interactions API](/docs/long-decode).

{% /callout %}

Long decode lets Gemini 4 models (`gemini-4-carbon`, `gemini-4-argon`, and `gemini-4-hydrogen`) generate past the single-request output limit for deep reasoning tasks, up to the unified 1M-token context window (1,048,576 tokens shared across input, thinking, and output).

Changing the model ID alone doesn't enable long decode. Without additional setup, output stops at 64K tokens on `gemini-4-hydrogen` (streaming and non-streaming), and at 64K tokens for streaming or SDK calls and 32K tokens for direct non-streaming REST calls on `gemini-4-carbon` and `gemini-4-argon`. The fastest way to turn on long decode is to upgrade the Google GenAI SDK and set `max_output_tokens` greater than 65,536. This guide explains how long decode works, when to use it, and how to turn it on with `generateContent`.

{% callout type="note" %}
  Automatic continuation needs these Google GenAI SDK versions or higher: Python (`google-genai`) 2.30.1, JavaScript (`@google/genai`) 2.29.1, Go 1.74.0, Java 1.77.0, .NET 1.26.0, and Kotlin 1.6.0. Earlier versions don't continue automatically. Output stops at 64K tokens.

{% /callout %}

## How long decode works  {% id="how-long-decode-works" %}

A single streaming request, SDK request, or `gemini-4-hydrogen` non-streaming REST request generates up to 64K tokens, while a direct non-streaming REST request on `gemini-4-carbon` or `gemini-4-argon` generates up to 32K tokens. When a response needs more tokens, the model generates it across multiple request-and-response hops that each continue from where the previous hop stopped.

* **Unified input and output token limit:** Input, thinking, function calls, and the final response share one 1M-token window. Output can use up to 1,048,576 minus your input tokens.
* **A cap on each hop:** One hop returns up to 65,536 output tokens (or up to 32,768 on direct non-streaming REST calls to `gemini-4-carbon` and `gemini-4-argon`).
* **A continuation signal:** If the model reaches the cap and has tokens left, the response ends with `finish_reason: CONTINUATION` and a `continuation_token`.
* **The next hop:** The client sends the same request again with the token. The model continues from where it stopped.
* **One total for all hops:** `max_output_tokens` sets the total thinking and output tokens for all hops together.
* **A stop signal:** When the model uses all of `max_output_tokens`, the response ends with `finish_reason: MAX_TOKENS`.

On hard problems, a hop can spend all of its tokens on internal thinking and return empty text with a `continuation_token`. This is normal, and the final answer arrives in later hops.

## Default output limits  {% id="default-output-limits" %}

Without long decode, a single request stops at these per-request limits:

* **Streaming requests, non-streaming requests through the Google GenAI SDK (`generate_content`), and all `gemini-4-hydrogen` calls:** Default to 64K (65,536) output tokens.
* **Direct non-streaming REST calls (`generateContent`) on `gemini-4-carbon` and `gemini-4-argon`:** Default to 32K (32,768) output tokens. Setting `max_output_tokens` greater than 32,768 on a non-streaming REST call to Carbon or Argon without a `continuation_token` returns a `400` error.

| How you call the model | Output limit without long decode | Long decode at launch | What to do |
| :--- | :--- | :--- | :--- |
| Google GenAI SDK, latest version | 64K | Yes, the SDK continues for you | Set `max_output_tokens`. |
| Google GenAI SDK, older version, non-streaming | 64K | No | Upgrade the SDK. |
| REST `streamGenerateContent` | 64K | Yes, with your own loop | Write a loop. See [Option 2](/docs/long-decode?generate-content=true#option-2-loop). |
| REST `generateContent` | 64K (`gemini-4-hydrogen`) or 32K (`gemini-4-carbon`, `gemini-4-argon`) | Yes, with your own loop | Write a loop. See [Option 2](/docs/long-decode?generate-content=true#option-2-loop). |

{% callout type="warning" %}
  Always set `max_output_tokens` greater than 65,536 for long decode. Also check the value in your agent framework or evaluation tool. A low value, such as 8,192, stops the model before it finishes thinking.

{% /callout %}

## When to use long decode  {% id="when-to-use-long-decode" %}

Most requests finish within the single-request limit (64K tokens, or 32K tokens for direct non-streaming REST calls on `gemini-4-carbon` and `gemini-4-argon`). Use long decode when a response needs more combined thinking and output tokens than a single request allows. Raising `max_output_tokens` gives the model a higher ceiling to reason through hard problems, rather than making standard answers longer.

| Workload | Use long decode? | Why |
| :--- | :--- | :--- |
| Hard math, science, research, and formal proofs | Yes | The model can spend more than 64K tokens to explore and check its reasoning. |
| The hardest coding and agentic tasks | Yes | Some tasks need more than 64K tokens of thinking and code in one response. Most coding and agentic tasks finish under 64K. |
| Evaluation harnesses that stop at the output limit | Yes | Long decode prevents cut-off answers when the model spends a whole 64K or 32K request on thinking. |
| Chat, Q&A, summarization, classification, and extraction | No | These tasks finish well under 32K tokens. |
| Requests for a fixed length, such as "write a 700,000-word book" | No | The model does not follow length targets. |
| Agents that call tools in many short turns | No | Each turn is short. Large outputs on each turn fill the unified 1M input and output window fast. |
| Prompts near the 1M input limit | No | Output can use only 1M minus your input. |
| Latency-sensitive requests | No | Long decode can run for several minutes. |

Setting a high `max_output_tokens` gives the model room to think longer on hard problems, but the model still decides how much to write. To control how much reasoning effort the model uses, set [`thinking_level`](/docs/thinking?generate-content=true).

## Turn on long decode  {% id="turn-on-long-decode" %}

You can run long decode automatically with the Google GenAI SDK (Option 1, recommended for most apps) or write your own continuation loop (Option 2). Both options support the full 1M-token context window.

|  | Option 1: Google GenAI SDK (recommended) | Option 2: Your own streaming loop | Option 2: Your own non-streaming loop |
| :--- | :--- | :--- | :--- |
| **Who starts each hop** | The SDK. You set `max_output_tokens`. | Your code, at each checkpoint or after a dropped stream | Your code, every 64K tokens (`gemini-4-hydrogen`) or 32K tokens (`gemini-4-carbon`, `gemini-4-argon`) |
| **Tokens per request** | 64K per hop | 64K per stream, with a checkpoint every 5K tokens after 32K on Carbon and Argon (or after 64K on Hydrogen) | 64K (`gemini-4-hydrogen`) or 32K (`gemini-4-carbon`, `gemini-4-argon`) per request |
| **Time limit per request** | 20 minutes | 20 minutes | 20 minutes |
| **Storage** | No server storage | No server storage | No server storage |
| **Best for** | Most applications | REST callers and custom harnesses that stream | Simple evaluation harnesses |

The encrypted `continuation_token` carries the model's state between requests, so nothing is stored on the server.

{% callout type="note" %}
  To work properly, long decode needs these Google GenAI SDK versions or higher: Python (`google-genai`) 2.30.1, JavaScript (`@google/genai`) 2.29.1, Go 1.74.0, Java 1.77.0, .NET 1.26.0, and Kotlin 1.6.0.

{% /callout %}

### Option 1: Use the Google GenAI SDK (recommended)  {% id="option-1-sdk" %}

In the latest Google GenAI SDK, `automatic_continuation` is enabled by default for both streaming and non-streaming calls, so you do not need to set it. When you set `max_output_tokens` above the per-request cap, the SDK automatically runs the continuation hops and returns one combined response.

1. Upgrade the SDK.

   {% tabs %}
     {% tab label="Python" %}
     ```bash
     pip install -U "google-genai>=2.30.1"
     ```

     {% /tab %}

     {% tab label="JavaScript" %}
     ```bash
     npm install "@google/genai@>=2.29.1"
     ```

     {% /tab %}

   {% /tabs %}

2. Set `max_output_tokens` greater than 65,536.

   {% tabs %}
     {% tab label="Python" %}
     ```python
     from google import genai
     from google.genai import types
     
     client = genai.Client()  # Reads GEMINI_API_KEY
     
     response = client.models.generate_content(
         model="gemini-4-carbon",
         contents="Write a complete, rigorous proof of the prime number theorem.",
         config=types.GenerateContentConfig(
             max_output_tokens=262_144,  # Total thinking and output for all hops
             thinking_config=types.ThinkingConfig(thinking_level="high"),
             automatic_continuation=True,  # Default. Shown for clarity.
         ),
     )
     
     print(response.text)
     print("Finish reason:", response.candidates[0].finish_reason)
     print("Prompt size:", response.usage_metadata.initial_prompt_token_count)
     print("Billed tokens:", response.usage_metadata.total_token_count)
     ```

     {% /tab %}

     {% tab label="JavaScript" %}
     ```javascript
     import { GoogleGenAI, ThinkingLevel } from "@google/genai";
     
     const ai = new GoogleGenAI({}); // Reads GEMINI_API_KEY
     
     const response = await ai.models.generateContent({
       model: "gemini-4-carbon",
       contents: "Write a complete, rigorous proof of the prime number theorem.",
       config: {
         maxOutputTokens: 262144, // Total thinking and output for all hops
         thinkingConfig: { thinkingLevel: ThinkingLevel.HIGH },
         automaticContinuation: true, // Default. Shown for clarity.
       },
     });
     
     console.log(response.text);
     console.log("Finish reason:", response.candidates?.[0]?.finishReason);
     console.log("Prompt size:", response.usageMetadata?.initialPromptTokenCount);
     console.log("Billed tokens:", response.usageMetadata?.totalTokenCount);
     ```

     {% /tab %}

   {% /tabs %}


Keep these points in mind:

* **Streaming:** `generate_content_stream` (Python) and `generateContentStream` (JavaScript) also continue for you. If a stream drops after a checkpoint, the SDK resumes from that checkpoint.
* **Timeouts:** Timeouts and retries apply to each hop, not to the full run.
* **Manual control:** To run the loop yourself, set `automatic_continuation=False` (Python) or `automaticContinuation: false` (JavaScript). Then follow Option 2.
* **Usage:** The usage fields show the sum of all hops. To get the size of your prompt, read `initial_prompt_token_count`. See [Count tokens](/docs/long-decode?generate-content=true#count-tokens).

### Option 2: Write your own loop  {% id="option-2-loop" %}

Write your own loop if you call REST directly, use a language without the latest SDK, or need full control. You can also refer to our Google GenAI SDK implementations in [Python](https://github.com/googleapis/python-genai/blob/v2.30.1/google/genai/models.py#L6111) and [JavaScript/TypeScript](https://github.com/googleapis/js-genai/blob/v2.29.1/src/models.ts#L88) as a reference.

Follow these rules:

1. **Send the same request on every hop.** Send the original `contents`, `system_instruction`, `tools`, and `generation_config`. Keep `max_output_tokens` the same.
2. **Do not add partial output to `contents`.** The `continuation_token` carries the model's state, including its thinking.
3. **Send only the latest token.** Each token contains all earlier progress.
4. **Continue while `finish_reason` is `CONTINUATION`.** Stop on any other finish reason.
5. **Join the parts after the last hop.** Combine the parts from all hops into one model turn for the conversation history.

{% tabs %}
  {% tab label="Python" %}
  ```python
  from google import genai
  from google.genai import types
  
  client = genai.Client()  # Reads GEMINI_API_KEY
  PROMPT = "Write a complete, rigorous proof of the prime number theorem."
  parts = []
  token = None
  
  while True:
      response = client.models.generate_content(
          model="gemini-4-carbon",
          contents=PROMPT,  # The original contents on every request
          config=types.GenerateContentConfig(
              max_output_tokens=262_144,  # The same total on every request
              thinking_config=types.ThinkingConfig(thinking_level="high"),
              automatic_continuation=False,  # You run the loop
              continuation_token=token,
          ),
      )
      candidate = response.candidates[0]
      if candidate.content and candidate.content.parts:
          parts.extend(candidate.content.parts)
      token = candidate.continuation_token
      if candidate.finish_reason != types.FinishReason.CONTINUATION or not token:
          break
  
  print("".join(p.text for p in parts if p.text and not p.thought))
  print("Finish reason:", candidate.finish_reason)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
  import { GoogleGenAI, ThinkingLevel } from "@google/genai";
  
  const ai = new GoogleGenAI({}); // Reads GEMINI_API_KEY
  const PROMPT = "Write a complete, rigorous proof of the prime number theorem.";
  const parts = [];
  let token = undefined;
  let candidate = undefined;
  
  while (true) {
    const response = await ai.models.generateContent({
      model: "gemini-4-carbon",
      contents: PROMPT, // The original contents on every request
      config: {
        maxOutputTokens: 262144, // The same total on every request
        thinkingConfig: { thinkingLevel: ThinkingLevel.HIGH },
        automaticContinuation: false, // You run the loop
        continuationToken: token,
      },
    });
    candidate = response.candidates?.[0];
    if (candidate?.content?.parts) {
      parts.push(...candidate.content.parts);
    }
    token = candidate?.continuationToken;
    if (candidate?.finishReason !== "CONTINUATION" || !token) {
      break;
    }
  }
  
  console.log(parts.filter((p) => p.text && !p.thought).map((p) => p.text).join(""));
  console.log("Finish reason:", candidate?.finishReason);
  ```

  {% /tab %}

  {% tab label="REST" %}
  ```bash
  # Hop 1: send the request with max_output_tokens.
  curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-carbon:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "contents": [{"role": "user", "parts": [{"text": "Write a complete, rigorous proof of the prime number theorem."}]}],
      "generationConfig": {
        "maxOutputTokens": 262144,
        "thinkingConfig": {"thinkingLevel": "high"}
      }
    }'
  
  # Hop 2: if finishReason is CONTINUATION, send the same request plus the token.
  curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-4-carbon:generateContent" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "contents": [{"role": "user", "parts": [{"text": "Write a complete, rigorous proof of the prime number theorem."}]}],
      "generationConfig": {
        "maxOutputTokens": 262144,
        "thinkingConfig": {"thinkingLevel": "high"}
      },
      "continuationToken": "TOKEN_FROM_HOP_1"
    }'
  ```

  {% /tab %}

{% /tabs %}

A hop spent entirely on thinking returns empty `text` with `finishReason: "CONTINUATION"`. Treat this as normal progress and request the next hop:

```json
{
  "candidates": [{
    "content": {"role": "model", "parts": [{"text": ""}]},
    "finishReason": "CONTINUATION",
    "continuationToken": "CiQ4ZmQ3..."
  }],
  "usageMetadata": {
    "promptTokenCount": 142,
    "candidatesTokenCount": 0,
    "thoughtsTokenCount": 32768,
    "totalTokenCount": 32910
  }
}
```

**Streaming loops** need one more rule. After the first 32,768 tokens on `gemini-4-carbon` and `gemini-4-argon` (or after 65,536 tokens on `gemini-4-hydrogen`, starting on the second hop), the stream sends a checkpoint token every 5,000 tokens. Keep new chunks in a pending list. When a chunk has a `continuation_token`, move the pending chunks to your committed output and save the token. If the stream drops, discard the pending chunks and resume from the last token. If the stream drops before the first checkpoint, send the original request again.

## Set `max_output_tokens` {% id="set-max-output-tokens" %}

`max_output_tokens` sets the combined limit for thinking and output across all hops. Lowering it doesn't make the model think more concisely, and instead cuts the response off sooner.

| Your workload | Recommended `max_output_tokens` |
| :--- | :--- |
| Existing apps with a limit lower than 32K | Raise it to 32,768. |
| Long coding and agentic tasks | Start at 65,536. |
| Hard math, science, research, and proofs | Test values from 262,144 up to 1,048,576 minus your input tokens. |

To use fewer tokens, lower `thinking_level`. Use `high` for the hardest reasoning tasks. Use `medium` (the default) for most coding and agentic work. Use `low` for less complex tasks.

## Handle long-running requests  {% id="handle-long-running-requests" %}

Because Gemini 4 models think longer than Gemini 3.x models on hard problems, you should increase your client timeouts so long requests don't disconnect early.

* **Non-streaming calls:** The server closes the connection after 10 minutes.
* **Streaming calls:** The server closes the stream after 20 minutes.
* **Client timeouts:** Set your HTTP read timeout to 20 minutes. A 3-minute or 5-minute timeout stops the request early.

In Python, set the timeout on the client in milliseconds:

```python
client = genai.Client(http_options=types.HttpOptions(timeout=1_200_000))  # 20 minutes
```

For jobs that your client polls, the Interactions API runs long decode on the server. See [background execution](/docs/background-execution).

## Resume when the model uses all output tokens  {% id="resume-max-output-tokens" %}

When a response ends with `MAX_TOKENS`, it still includes a `continuation_token`. You have two choices:

* **Continue:** Send the same request with the token and a higher `max_output_tokens`. The value must be above the tokens used so far. Otherwise, the API returns a 400 error.
* **Start again:** Send the original request with a higher `max_output_tokens` and no token. You pay for both runs.

## Count tokens  {% id="count-tokens" %}

With automatic continuation, `usage_metadata` reports the totals across all hops. The SDK adds up every count field: `prompt_token_count`, `cached_content_token_count`, `candidates_token_count`, `thoughts_token_count`, and `total_token_count`.

`prompt_token_count` adds up the input tokens of every hop. Each hop sends your prompt plus everything generated so far back to the model as input, so the same tokens are counted again in every later hop. For example, with the Google GenAI SDK, a 1,000-token prompt that produces 200,000 tokens of thinking and output takes four hops:

| Hop | Input sent to the model | Input tokens |
| :--- | :--- | ---: |
| 1 | Prompt | 1,000 |
| 2 | Prompt + hop 1 | 66,536 |
| 3 | Prompt + hops 1 and 2 | 132,072 |
| 4 | Prompt + hops 1 to 3 | 197,608 |
| **Total** |  | **397,216** |

`prompt_token_count` reports about 397,000 tokens (with repeated hop inputs automatically discounted 95% by implicit caching), and `total_token_count` reports about 597,000 tokens, even though the actual context size is only about 201,000 tokens: the 1,000-token prompt plus 200,000 tokens of thinking and output. On `gemini-4-carbon` and `gemini-4-argon`, a non-streaming REST loop uses 32K hops, so it takes seven hops for the same output and reports 695,128 input tokens (`gemini-4-hydrogen` uses 64K hops for both streaming and non-streaming).

| How you call the model | What `usage_metadata` shows | For cost | For the prompt size |
| :--- | :--- | :--- | :--- |
| Google GenAI SDK, automatic continuation (the default) | Totals across all hops | Read the usage fields as is. | Read `usage_metadata.initial_prompt_token_count` (Python) or `usageMetadata.initialPromptTokenCount` (JavaScript). |
| SDK with `automatic_continuation=False`, or REST | One hop per response | Add each field across hops. | Read `prompt_token_count` from the first hop. |

`prompt_token_count` and `total_token_count` are the sum of every hop, not the size of your context. Don't use them to decide when to summarize or trim your conversation history (context compaction), or to enforce a context limit. To estimate the context size, add your prompt size from the table to `candidates_token_count` and `thoughts_token_count`.

Update your agent framework, evaluation tool, or proxy before you run long decode:

* **Agents and evaluation tools:** If your code compacts context or stops a run at a token limit, use `initial_prompt_token_count` (or the first hop's `prompt_token_count` in REST) instead of the summed `prompt_token_count`. Responses that finish in one hop report the same value in both fields, so short tests don't show the problem.
* **Proxies and gateways that call REST:** Each REST response reports only its own hop. Add each field across hops for cost, and keep the first hop's `promptTokenCount` as the prompt size. Otherwise, your users see different numbers than SDK users see for the same request.
* **Logs and serialized responses:** The SDK calculates `initial_prompt_token_count` on the client. It isn't in the REST response or in the SDK's JSON output, such as `model_dump()`. Save it as a separate value if you need it later.

If you stream in your own loop, `usage_metadata` is cumulative within each stream. Keep only the last value of each stream, then add the values across hops.

## Understand billing  {% id="understand-billing" %}

You pay for every token in every hop, including hops that contain only thinking.

* **Cache discount:** Implicit caching discounts the repeated input in each hop by 95%. Cached input costs $0.10 per 1M tokens instead of $2.00 during the introductory period.
* **Cache expiry:** The cache expires after 15 to 20 minutes without use. A long pause between hops charges the full input rate again.
* **Failed non-streaming hops:** You pay only when a response completes. A failed or dropped request costs $0.
* **Dropped streams:** A stream that drops before the first checkpoint (32K tokens on Carbon and Argon, or 64K tokens on Hydrogen) costs $0. After that, you pay up to the last checkpoint token, because you can resume from it.

## Troubleshooting  {% id="troubleshooting" %}

| Symptom | Cause and fix |
| :--- | :--- |
| Output stops at 64K or 32K with `CONTINUATION` | The model has tokens left, but nothing continued the request. Upgrade the SDK or add a loop. |
| Output stops at 64K or 32K with `MAX_TOKENS` | `max_output_tokens` is not set or is too low. Set it to more than 65,536. |
| Empty text with `MAX_TOKENS` | The model used all tokens on thinking. Raise `max_output_tokens` or lower `thinking_level`. |
| 400: "Continuation token has already used output tokens..." | `max_output_tokens` is not above the tokens used so far. Raise it. |
| Error for `thinking_level: "minimal"`, or for `thinking_budget` with `thinking_level` | Gemini 4 models (`gemini-4-carbon`, `gemini-4-argon`, and `gemini-4-hydrogen`) do not support `minimal`. Use `low`, `medium`, or `high` (plus `xhigh` on `gemini-4-hydrogen`). Set `thinking_level` or `thinking_budget`, not both. |
| Warning for `thinking_budget`, `temperature`, `top_p`, or `top_k` | Gemini 4 models ignore or map these fields. Use `thinking_level`, and remove the sampling parameters. |
| Request ends after 3 or 5 minutes | The client timeout is too short. Set it to 20 minutes. |
| Context compaction starts too early | The harness reads summed input. Read `initial_prompt_token_count` instead. |

## Limitations  {% id="limitations" %}

* **OpenAI compatibility endpoint:** Long decode is not available. Output stops at the per-request cap.
* **Older SDKs:** Versions below the minimums in the note do not continue automatically.
* **Length:** The model does not follow token-length or word-count targets.

## Checklist  {% id="checklist" %}

* Upgrade the Google GenAI SDK to the minimum version.
* Set `max_output_tokens` greater than 65,536.
* Use `thinking_level` (`low`, `medium`, or `high`), not `thinking_budget`.
* Set HTTP read timeouts to 20 minutes.
* Use `initial_prompt_token_count` for context size and compaction.
* Run one prompt as a test before a large evaluation.

## Next steps  {% id="next-steps" %}

* Learn about the [latest Gemini models](/docs/latest-model?generate-content=true)
* [Thinking](/docs/thinking?generate-content=true)
* [Token counting](/docs/tokens?generate-content=true)

