DEV Community

Anup Karanjkar
Anup Karanjkar

Posted on Originally published at wowhow.cloud

Gemini 4 Neon API Migration Guide: Pricing and Breaks

Gemini 4 Neon (gemini-4-neon) costs $3.00 per million input tokens and $15.00 per million output tokens, and thinking tokens bill as output.[1] From Carbon, Argon or Hydrogen, Google lists no request schema changes: set the model string, then check the default thinking level. From Gemini 3.x, six things break: the default thinking level moves to high, minimal returns an error, explicit caching is gone, temperature, top_p and top_k are ignored or rejected, output caps share one window with input, and prompts that fake tool calls in raw text can fail with MALFORMED_FUNCTION_CALL.[1] Below: the what-breaks table, worked cost math with the 95% cache discount, and a Neon vs Carbon vs Hydrogen decision table.

What launched, in one paragraph

Google announced Neon on November 18, 2026, with a 1 million-token context window and availability in the Gemini API in Google AI Studio.[2] The API docs position it between Gemini 4 Hydrogen and Gemini 4 Carbon, aimed at complex software engineering, knowledge work and science workflows.[1] It is paid-tier only and is not available on the free tier.[1]

Google's launch post reports that Neon scores 61 on the Artificial Analysis Intelligence Index at its xhigh level and 65.2% on Terminal-Bench 4.1. Both are vendor-reported figures, so treat them as a reason to run your own evaluation, not as a result.[2] The numbers that matter for a migration are in the API docs, and they are below.

Neon pricing

Pricing is flat across the whole 1M window. There is no long-context surcharge tier.[1]

Token type Price per 1M tokens Notes

| Input | $3.00 | Flat across the full context window |

| Cached input | $0.15 | Implicit caching, 95% discount on cache hits |

| Output, including thinking | $15.00 | Thinking tokens bill at the output rate |

Google bills every token the model processes. That includes thinking tokens, and with grounding it includes internal tool system instructions and function declarations. Grounding with Google Search is billed per query on top.[1] So a token counter run on your visible prompt will undercount. Add the declarations and the thinking.

Worked example: one agent call with a cached prefix

Take a code-review call with a 200,000-token input. The first 150,000 tokens are a repository snapshot and instructions that repeat across calls, and they hit the implicit cache. The remaining 50,000 are the diff and the question. The model spends 14,000 tokens thinking and writes 6,000 visible tokens, so 20,000 output-rate tokens.

INPUT = 3.00 / 1_000_000      # USD per input token
CACHED = 0.15 / 1_000_000     # USD per cached input token (95% off)
OUTPUT = 15.00 / 1_000_000    # USD per output token, thinking included

fresh_in = 50_000
cached_in = 150_000
out_tokens = 14_000 + 6_000   # thinking + visible answer

with_cache = fresh_in * INPUT + cached_in * CACHED + out_tokens * OUTPUT
no_cache = (fresh_in + cached_in) * INPUT + out_tokens * OUTPUT

print("with cache: $%.4f" % with_cache)   # $0.4725
print("no cache:   $%.4f" % no_cache)     # $0.9000
Enter fullscreen mode Exit fullscreen mode

The arithmetic: 50,000 fresh input tokens cost $0.15, 150,000 cached tokens cost $0.0225, and 20,000 output tokens cost $0.30. Total $0.4725. Without the cache, 200,000 input tokens cost $0.60, plus the same $0.30 of output, gives $0.90. The cache cuts this call by 47.5%, and the remaining bill is about 63% output. Input caching is not where the money goes once thinking is on. Thinking depth is.

Two limits on that discount. Implicit caching runs by default on prompts of at least 4,096 tokens, and Neon does not support explicit caching at all.[1] You cannot pin a cache. You can only keep your prefix stable and hope the hit rate holds, so measure it in the usage data instead of assuming 95% across the board.

What breaks moving from Gemini 3.x

Google's migration checklist lists no request schema changes between Gemini 4 siblings, and a longer list for Gemini 3 and earlier. The table condenses the Gemini 3 and earlier items from the docs, using gemini-3.8-flash as the reference point.[1]

Area Gemini 3.x behavior Neon behavior Fix

| Model ID | gemini-3.8-flash or earlier | gemini-4-neon | Change the model string |

| Context budget | Separate 1M input and 64K output budgets (3.8 Flash) | One 1,048,576-token window shared by input, thinking and output; 65,536 per synchronous response | Raise or remove low max_output_tokens caps |

| Thinking level | Default medium | Default high, adds xhigh, rejects minimal with an error | Set thinking_level explicitly; test medium and high |

| Caching | Explicit caching available | No cachedContents or caches.create; implicit caching only | Remove cached_content fields |

| Sampling | temperature, top_p, top_k | In-range custom values ignored; out-of-range values return a 400 | Delete the parameters |

| Tool calls | Not covered in the docs | Can return MALFORMED_FUNCTION_CALL with zero declared tools | Declare tools natively or use structured output |

| Conversation state | Not covered in the docs | Use previous_interaction_id (Interactions API); return thought signatures unchanged in generateContent histories | Do not copy a signature across parallel functionCall parts |

| Timeouts | Not covered in the docs | Hard prompts can take several minutes | Use background execution or set HTTP timeouts to at least 15 minutes |

Three of these fail quietly. The sampling parameters do not error when they are in range, so a leftover temperature: 0.2 keeps working while doing nothing, and your team keeps believing it controls determinism. The 8,192 cap is the other quiet one: the docs tell you to remove hardcoded caps like 8,192 because max_output_tokens covers thinking plus answer, and a low cap can cut the answer short.[1] The third is the timeout: the docs say hard prompts can take several minutes, so any gateway or client with a short idle limit in front of the API is a risk.

Thinking levels are the cost dial

Neon supports four levels: low, medium, high (default) and xhigh. Google's guidance is to start at high, reserve xhigh for hard multi-step problems where high falls short, and run evaluations at all four levels with a high max_output_tokens so the cap does not truncate answers. Then pick the lowest level that meets your quality bar.[1]

Because thinking bills at $15 per million, the level is a price decision. Every 100,000 thinking tokens saved is $1.50 saved. The docs give no per-level token counts, so the only honest way to price a level is to run your own prompts and read the usage object. Google's launch post claims Neon at high costs 32% less per task than Carbon on a third-party index, which is vendor-reported and specific to that benchmark.[2]

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-neon",
    input="Audit this payment retry queue for race conditions and rewrite the lock acquisition logic.",
    generation_config={
        "thinking_level": "xhigh"
    }
)

print(interaction.output_text)
Enter fullscreen mode Exit fullscreen mode

This is the Interactions API call from Google's docs. Omit generation_config and you get high and a 64K synchronous output limit.[1] Worth a routing rule: send everything at high, and re-run only the failures at xhigh.

Long outputs: background execution and the worst-case bill

Synchronous responses stop at 65,536 tokens per hop. To go past that, set max_output_tokens above 65,536 (up to 1,048,576 minus your input tokens) and set background to true, so the server continues in 64K hops. Set background without max_output_tokens and the server stops at 65,536.[1]

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-4-neon",
    input="Generate a complete multi-module migration specification and test suite for this service.",
    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)

# Join text across all 64K continuation hops.
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)
Enter fullscreen mode Exit fullscreen mode

This sample matches the long-decode example in Google's docs.[1] It also gives you a ceiling to budget against. A 262,144-token cap is at most 262,144 × $15 / 1,000,000 = $3.93 of output per call, before input. The 8,192 cap many apps still carry tops out at $0.12. Set the cap to the worst bill you will accept, not the one that feels safe.

For retry logic around long calls, the exponential backoff calculator turns a base delay, multiplier and attempt count into a schedule. If you forward prompts through a proxy, run them through the JSON formatter first to catch malformed tool declarations before they reach the API.

Neon, Carbon or Hydrogen

Only facts from Google's docs go in this table. Carbon and Hydrogen prices are not listed here because they were not part of the Neon pages; check the pricing page before costing a switch.

Model Default thinking level Levels supported Positioning in Google's docs

| Gemini 4 Neon | high | low, medium, high, xhigh | Complex software engineering, knowledge work and science; frontier-level intelligence with fast end-to-end completion |

| Gemini 4 Carbon | medium | Caps at high | Hardest architecture, debugging, science and security problems |

| Gemini 4 Hydrogen | high | Supports xhigh | Default for everyday coding and agentic workflows |

That default column is the trap when you move between siblings. Carbon defaults to medium, Neon to high, so an unchanged Carbon-to-Neon swap changes your token spend even though the request schema is identical.[1] Pin thinking_level in code on both sides of any A/B test.

Google's launch post says Neon can act as an orchestrator directing parallel Hydrogen subagents in Antigravity, and the docs say the Antigravity agent in Managed Agents supports Neon standalone or paired with Hydrogen.[1][2] For the full three-way price comparison, see Gemini 4 Carbon vs Hydrogen vs Argon pricing. If you are weighing a different vendor's migration at the same time, the GPT-6.2 Astra and Sol migration guide covers the same checklist for OpenAI.

Migration order

  1. Confirm the project is on the paid tier. Neon is not available on the free tier.

  2. Change the model ID to gemini-4-neon and set thinking_level explicitly.

  3. Strip temperature, top_p, top_k and any cached_content fields.

  4. Raise or delete max_output_tokens caps below 65,536, or move long jobs to background.

  5. Replace raw-text tool-call prompts with declared tools or structured output.

  6. Raise HTTP client timeouts to 15 minutes or more.

  7. Re-run your evaluation at medium, high and xhigh, then keep the cheapest level that passes.

If your workload is short, cache-friendly and already passes on Hydrogen, the price table gives no reason to move. Neon earns its $15 output rate when high or xhigh solves tasks that cost you retries elsewhere, and only your evaluation can show that.

Sources

  1. What's new in Gemini 4 Neon, Gemini API documentation, Google AI Studio (accessed 2026-11-20)

2. Introducing Gemini 4 Neon, Google blog, November 18, 2026 (accessed 2026-11-20)

Originally published at wowhow.cloud

Top comments (0)