Gemini 4 Migration Guide

What’s New

Gemini 4 Argon, the first Gemini 4 model, returns at most 65,536 output tokens per request (its per-request output limit), but it can keep working on one answer for up to 1M output tokens in total. See the model page for current limits. Google calls this long decode. When a response stops at the per-request limit or uses up its max_tokens budget, it returns a continuation token. You send that token back in your next request, and the model picks up where it left off. On OpenRouter, the continuation token is an encrypted reasoning item. Clients that already pass reasoning back between turns get long decode with no new fields. This guide covers:

How long decode works: the total budget, when a token is returned, and what each hop costs
Chat Completions, Responses, and Anthropic Messages request shapes
Reasoning effort: the supported reasoning.effort values
Limits and routing: token size, provider pinning, and reasoning.exclude

How Long Decode Works

`max_tokens` is a total budget

Set max_tokens (or max_output_tokens on the Responses API) to the total number of output tokens you allow for the whole answer, across every hop. Do not subtract what earlier hops used: Google tracks the running total and stops once it is spent. After a CONTINUATION hop you can resend the same value. After a MAX_TOKENS hop the budget is spent, so raise it to continue.

`max_tokens`	Behavior
At or below the per-request limit	A normal single request. If the model hits the limit, the response ends with `finish_reason: "length"` and `native_finish_reason: "MAX_TOKENS"` and returns a continuation token. Raise `max_tokens` to continue
Above the per-request limit	Long decode. If the model reaches the per-request limit with budget left, the response ends with `finish_reason: "length"`, `native_finish_reason: "CONTINUATION"`, and a continuation token

When max_tokens is omitted, OpenRouter sends its default output budget of 65,536 tokens, the same as Argon’s per-request limit. A response that reaches it ends with MAX_TOKENS and a continuation token, so raise max_tokens to continue. max_tokens is cumulative across hops. A response that ended with MAX_TOKENS has spent its whole budget but still returns a continuation token: resend it with a higher max_tokens to continue. Resending it with the same max_tokens returns a 400 error. Raising max_tokens on a resume also works after CONTINUATION, so one rule covers both cases: set max_tokens above the total output of every hop so far.

At high effort the model can spend a hop’s full per-request limit on reasoning and return little or no visible text in that hop. A hop with empty content and native_finish_reason: "CONTINUATION" is normal: resume it.

The continuation loop

Send your request with max_tokens above the per-request limit.
If the response stopped at a length limit (Chat Completions finish_reason: "length", Responses status: "incomplete" with incomplete_details.reason: "max_output_tokens", Messages stop_reason: "max_tokens"), keep the stopped turn with its continuation items (reasoning details or Responses API reasoning items whose id is gemini-continuation). Gemini stops this way on both CONTINUATION and MAX_TOKENS finishes.
Resend the same conversation and parameters with the stopped turn appended as the last assistant turn. Set max_tokens above the total output of every hop so far, or the request returns a 400 error after a MAX_TOKENS hop.
Repeat until a response finishes without a length stop. Concatenate the visible text from every hop to get the full answer, and add up the usage of every hop.

Change nothing else between hops. The continuation token holds the model’s progress on the stopped turn, so the conversation before it must be resent unchanged. Do not add a new user message in the middle of a continuation. Only a continuation item in the last assistant turn resumes the decode. Each hop replaces the previous continuation turn, and OpenRouter removes continuation items from earlier turns, so a finished long answer in your history does not affect later requests. Visible text from the stopped turn does not need to be resent: OpenRouter drops the trailing continuation turn before forwarding the request, because the token already carries its state. Treat the token as opaque and pass it back byte for byte. A streaming hop can return more than one continuation item: one for each checkpoint Gemini saves while it generates, plus one when the hop stops at a limit. A hop that finishes normally can still carry checkpoint items, so decide whether to continue from the finish reason, not from whether an item is present. OpenRouter resumes from the last continuation item in the turn, so you can pass the stopped turn back unchanged. Keeping only the latest item makes the request smaller. The sections below show only the response and request shapes for each API.

Each hop is a separate billed request

Every hop is its own generation with its own usage and cost. A continuation hop’s prompt tokens include all the reasoning from earlier hops, and each hop bills its full prompt, so input cost grows with every hop. Implicit caching can cover part of that prompt, and cached tokens bill at the cached input rate. Explicit caching with cache_control is skipped on continuation hops. The sum of every hop’s usage is the total cost of a long answer. Use that sum for cost only: for context-window or compaction checks, use the first hop’s prompt_tokens, because the summed prompt tokens count earlier output once per hop and are much larger than the context the model uses. max_tokens caps the output tokens, not the input that earlier hops add back. See the model page for current rates.

Chat Completions API

A hop that stops at a limit returns the continuation token in reasoning_details:

{
  "choices": [
    {
      "finish_reason": "length",
      "native_finish_reason": "CONTINUATION",
      "message": {
        "role": "assistant",
        "content": "",
        "reasoning_details": [
          {
            "type": "reasoning.encrypted",
            "id": "gemini-continuation",
            "format": "google-gemini-v1",
            "data": "<opaque continuation token>",
            "index": 0
          }
        ]
      }
    }
  ]
}

To continue, append the assistant message with its reasoning_details and resend:

{
  "model": "google/gemini-4-argon",
  "max_tokens": 262144,
  "reasoning": { "effort": "high" },
  "messages": [
    { "role": "user", "content": "Prove that ..." },
    {
      "role": "assistant",
      "content": "",
      "reasoning_details": [
        {
          "type": "reasoning.encrypted",
          "id": "gemini-continuation",
          "format": "google-gemini-v1",
          "data": "<opaque continuation token>"
        }
      ]
    }
  ]
}

When streaming, continuation items arrive in delta.reasoning_details chunks during the stream, as Gemini saves checkpoints, and at the end of a hop that stops at a limit. A non-streaming response carries only the hop’s final item. If the stream drops partway, discard the text and reasoning received after the latest item, then resend that item as the last assistant turn with the same max_tokens to resume from that checkpoint. The resumed hop regenerates everything after the checkpoint. If the stream drops before the first item arrives, there is no checkpoint to resume from, so resend the original request. A dropped stream reports no usage or finish reason, so you cannot tell whether the dropped hop had already spent its budget. If the resume returns a 400 error saying max_output_tokens has been exhausted, raise max_tokens and resend. A loop in TypeScript:

type Message = { role: string; content: string; reasoning_details?: unknown[] };

const conversation: Message[] = [{ role: 'user', content: 'Prove that ...' }];
let continuation: Message | undefined;
let maxTokens = 262_144;
let answer = '';
let promptTokens = 0;
let completionTokens = 0;

while (true) {
  const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'google/gemini-4-argon',
      max_tokens: maxTokens,
      reasoning: { effort: 'high' },
      messages: continuation ? [...conversation, continuation] : conversation,
    }),
  });
  if (!response.ok) {
    throw new Error(`OpenRouter returned ${response.status}: ${await response.text()}`);
  }
  const { choices, usage } = await response.json();
  const [choice] = choices;
  answer += choice.message.content ?? '';
  promptTokens += usage.prompt_tokens;
  completionTokens += usage.completion_tokens;

  const latestContinuation = choice.message.reasoning_details?.findLast(
    (detail: { id?: string }) => detail.id === 'gemini-continuation',
  );
  if (choice.finish_reason !== 'length' || !latestContinuation) {
    break;
  }
  if (choice.native_finish_reason === 'MAX_TOKENS') {
    maxTokens = completionTokens + 262_144;
  }

  continuation = {
    role: 'assistant',
    content: '',
    reasoning_details: [latestContinuation],
  };
}

Responses API

A hop that stops at a limit returns status: "incomplete" with incomplete_details.reason: "max_output_tokens" and a reasoning output item that carries the token in encrypted_content. A streaming hop can return one such item per checkpoint, and a completed response can carry them too, so resume only when status is "incomplete" and incomplete_details.reason is "max_output_tokens". Other incomplete reasons, such as content_filter, cannot be resumed:

{
  "status": "incomplete",
  "incomplete_details": { "reason": "max_output_tokens" },
  "output": [
    {
      "type": "reasoning",
      "id": "gemini-continuation",
      "summary": [],
      "encrypted_content": "<opaque continuation token>",
      "format": "google-gemini-v1"
    }
  ]
}

To continue, append the reasoning item to input:

{
  "model": "google/gemini-4-argon",
  "max_output_tokens": 262144,
  "reasoning": { "effort": "high" },
  "input": [
    { "role": "user", "content": "Prove that ..." },
    {
      "type": "reasoning",
      "id": "gemini-continuation",
      "summary": [],
      "encrypted_content": "<opaque continuation token>",
      "format": "google-gemini-v1"
    }
  ]
}

The Responses API returns this same shape for CONTINUATION and MAX_TOKENS hops, so set max_output_tokens above the total output of every hop so far on each resume. Resending a spent budget returns a 400 error. This is the stateless pattern the Responses API already uses for encrypted reasoning. OpenRouter does not store the response, so previous_response_id cannot be used to continue.

Anthropic Messages API

A hop that stops at a limit returns stop_reason: "max_tokens" and a redacted_thinking content block that carries the token. A streaming hop can return one such block per checkpoint, interleaved with text:

{
  "role": "assistant",
  "stop_reason": "max_tokens",
  "content": [{ "type": "redacted_thinking", "data": "<opaque continuation data>" }]
}

To continue, append the assistant turn with the redacted_thinking block:

{
  "model": "google/gemini-4-argon",
  "max_tokens": 262144,
  "messages": [
    { "role": "user", "content": "Prove that ..." },
    {
      "role": "assistant",
      "content": [{ "type": "redacted_thinking", "data": "<opaque continuation data>" }]
    }
  ]
}

Messages returns this same shape for CONTINUATION and MAX_TOKENS hops, so set max_tokens above the total output of every hop so far on each resume. Resending a spent budget returns a 400 error. Messages has no native finish reason field. Resume only when stop_reason is "max_tokens", and pass the assistant content back unchanged: continuation blocks look like other redacted_thinking blocks, such as thought signatures, and OpenRouter resumes from the last continuation block. A dropped stream has no stop_reason; resend the content received up to and including the latest redacted_thinking block. The data value wraps the Gemini token in an OpenRouter envelope so its format survives the round trip.

Reasoning Effort

Gemini 4 Argon always reasons. reasoning.effort accepts low, medium, and high. reasoning.max_tokens is not supported, and reasoning cannot be turned off.

Limits and Routing

Token size grows with the decode and can reach several MB for a long answer. Your client must accept and resend bodies of that size on later hops.
Continuations stay on one provider. A continuation token only works on the provider that issued it. OpenRouter routes a continuation request back to that provider and does not fall back to another one. If that provider is unavailable, the request fails instead of restarting the answer elsewhere.
reasoning.exclude keeps the token. With reasoning: { "exclude": true }, reasoning text is hidden but the continuation item is still returned, so long decode keeps working.

Migration Checklist

To keep single-request behavior, omit max_tokens or set it at or below the per-request limit.
To enable long decode, set max_tokens above the per-request limit, as the total budget for the whole answer, and run the continuation loop. A response that stops with MAX_TOKENS can also be continued later by raising max_tokens.
Use reasoning.effort low, medium, or high instead of reasoning.max_tokens. Reasoning cannot be turned off.

Breaking Changes

Compared with earlier Gemini models:

Length stops can be resumed. A response that reaches the per-request limit or the max_tokens budget returns a continuation token. A request that sets max_tokens above the per-request limit ends with native_finish_reason: "CONTINUATION" instead of MAX_TOKENS when it reaches the limit. A client that does not resume gets a partial answer, as with any length stop.
No reasoning budget. reasoning.max_tokens does not set a thinking budget, and reasoning cannot be turned off. Use reasoning.effort.

Other Gemini models are unaffected.

Resources

Reasoning Tokens, including how to preserve reasoning_details across turns
OpenRouter Responses API

Get Started

Working with Coding Agents

Building Agents

Video Generation

Audio

Image Generation

Evaluate & Optimize

Administration

Gemini 4 Migration Guide

What’s New

How Long Decode Works

`max_tokens` is a total budget

The continuation loop

Each hop is a separate billed request

Chat Completions API

Responses API

Anthropic Messages API

Reasoning Effort

Limits and Routing

Migration Checklist

Breaking Changes

Resources

​What’s New

​How Long Decode Works

​max_tokens is a total budget

​The continuation loop

​Each hop is a separate billed request

​Chat Completions API

​Responses API

​Anthropic Messages API

​Reasoning Effort

​Limits and Routing

​Migration Checklist

​Breaking Changes

​Resources

What’s New

How Long Decode Works

`max_tokens` is a total budget

The continuation loop

Each hop is a separate billed request

Chat Completions API

Responses API

Anthropic Messages API

Reasoning Effort

Limits and Routing

Migration Checklist

Breaking Changes

Resources