Gemini 4 Neon API: Model ID, Thinking Levels and a Checked First Request
Call gemini-4-neon on a paid Gemini API project, choose high or xhigh thinking, read thinking and cached-token usage, and fix the errors that differ from Carbon.
To call Gemini 4 Neon, send model: "gemini-4-neon" from a Gemini API project on the paid tier; Neon has no free tier. It thinks at high by default, also accepts low, medium and xhigh, and shares one 1,048,576-token window across input, thinking and output. Google’s Neon guide starts new code on the Interactions API, while generateContent also works. A request has only succeeded when the interaction is completed (or the candidate stopped with STOP), visible text is present, and the usage record shows what you will be billed for, thinking tokens included.
Google released gemini-4-neon as generally available on November 18, 2026. This guide was checked against Google’s documentation on November 19, 2026. It concentrates on what is specific to Neon. Project setup, API keys and billing are the same as for the other paid Gemini 4 model, so they are covered once in our Gemini 4 Carbon API setup guide and only summarised here.
Two limits on this article:
- Neon is not available on Ofox. We checked the Ofox model list (
GET https://api.ofox.ai/v1/models) on November 19, 2026: it listsgoogle/gemini-4-hydrogenandgoogle/gemini-4-argon, not Neon, andhttps://ofox.ai/models/google/gemini-4-neonreturned 404. Every example below uses Google’s native endpoint and a Google API key. Ofox publishes this blog. - We did not make a live Neon call. We had no Google key for this guide. The request bodies were checked against Google’s published contract (Neon guide, Interactions and
generateContentreferences, thinking, caching and long decode docs). The response checker was tested offline against 15 synthetic responses. That proves the parser logic. It does not prove authentication, latency or answer quality.
Gemini 4 Neon API facts at a glance
All values below come from Google’s What’s new in Gemini 4 Neon guide, the pricing page and the Neon model card, checked November 19, 2026.
| Item | Neon value |
|---|---|
| Model ID | gemini-4-neon (no -preview suffix) |
| Access | Gemini API paid tier only; also Google AI Studio with Google AI Pro and Ultra plans |
| APIs | Interactions API (Google’s quickstart) and generateContent |
| Thinking levels | low, medium, high (default), xhigh; minimal is rejected |
| Context | 1,048,576 tokens shared by input, thinking and output |
| Synchronous output | 65,536-token default and cap per hop, streaming and non-streaming |
| Longer output | Background execution or client-side continuation, up to 1M minus input |
| Standard price (USD per 1M tokens) | $3.00 input, $0.15 cached input, $15.00 output including thinking |
| Caching | Implicit only, from 4,096 prompt tokens; explicit cachedContents not supported |
| Sampling | temperature, top_p, top_k ignored when in range; out-of-range values return 400 |
| Knowledge cutoff | March 2026 (model card) |
Neon has no introductory price, unlike Carbon’s rate that ends November 30. For cost per task by thinking level, see our Gemini 4 Neon pricing breakdown.
What changes from a Carbon or Hydrogen request
Google states that switching from another Gemini 4 model to Neon “requires no request schema changes”. The fields stay the same; the values and limits around them change. If you already have working code from our Carbon or Hydrogen setup guides, these are the differences to account for.
| Area | Carbon | Hydrogen | Neon |
|---|---|---|---|
| Model ID | gemini-4-carbon | gemini-4-hydrogen | gemini-4-neon |
| Free tier | No | Yes | No |
| Default thinking | medium | high | high |
xhigh | Not supported | Supported | Supported |
| Non-streaming hop | 32,768 tokens per raw REST hop | 65,536 | 65,536 |
| Sampling parameters | Ignored | In range ignored, out of range 400 | In range ignored, out of range 400 |
| Standard price (input / output) | $2 / $10 to Nov 30, then $4 / $20 | $1.50 / $7.50 | $3 / $15, flat |
Sources: the Carbon, Hydrogen and Neon “What’s new” guides and the Choosing a model page. The 32,768 versus 65,536 hop comparison is stated in Google’s Hydrogen guide.
Three practical consequences follow:
- Moving from Carbon raises your default spend per call. Carbon defaults to
medium; Neon defaults tohigh. Code that never setthinking_levelwill think more on Neon without any change on your side. Set the level explicitly so the behaviour is visible in code review. - Moving from Hydrogen can break on the key, not the request. A Hydrogen integration may run on a free-tier project. The same key will not reach Neon. Check which project the key belongs to before debugging the payload.
- Code written for Neon may break on Carbon.
xhighis valid for Neon and Hydrogen but not for Carbon or Argon. If you route steps between models, make the thinking level part of the route, not a global constant. Our Neon vs Carbon comparison covers when each model is worth its price.
Step 1: Confirm the key belongs to a paid project
Neon needs four things to line up: a Google account allowed to use the Gemini API, a project in Google AI Studio, an API key that belongs to that project, and active paid-tier billing on the same project. Google’s billing guide describes the move from free to paid tier as linking a billing account to a project, and the Projects page shows each project’s billing tier. A Google AI Pro or Ultra plan gives you Neon in AI Studio, but don’t treat it as proof that your API key’s project is on the paid tier. Check the project’s tier on that page.
The step-by-step version (importing a Cloud project, key types and restrictions, prepay versus postpay) is in the Carbon setup guide’s first section and applies to Neon unchanged. Google’s sources are the API key guide and billing guide.
Keep the key in an environment variable and check it is loaded without printing it:
export GEMINI_API_KEY="..." # set in your shell or secret manager, never commit it
python3 -c 'import os; print("Key configured:", bool(os.environ.get("GEMINI_API_KEY")))'
True only means a value exists. The first request is what proves the project can reach Neon.
Step 2: Send the first request with the Interactions API
Google’s Neon quickstart uses the Interactions API, so start there for new code. Install the current SDK (google-genai, imported as from google import genai; not the older google-generativeai package):
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade google-genai
Save this as neon_first_call.py:
import json
import os
from pathlib import Path
from google import genai
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
interaction = client.interactions.create(
model="gemini-4-neon",
input="List exactly three checks for confirming a new API integration works.",
store=False,
generation_config={
"thinking_level": "low",
"max_output_tokens": 65536,
},
)
Path("neon-response.json").write_text(
json.dumps(interaction.model_dump(mode="json"), indent=2), encoding="utf-8"
)
print("Status:", interaction.status)
print("Usage:", interaction.usage)
print(interaction.output_text)
Three choices in this request are deliberate:
thinking_level: "low"keeps the access check cheap. Neon would otherwise think athigh. Uselowto prove the route, then set the level your real workload needs (Step 5).max_output_tokens: 65536is Neon’s documented default and per-hop cap. It is a ceiling on thinking plus visible output, not a prediction of the bill. Google advises against carrying over low caps such as 8,192 from older apps; lower the thinking level instead if you want to spend less.store=Falseopts this one-shot call out of storage. Leave storage on (the default) if you will usebackground=Trueorprevious_interaction_id; both need stored interactions. Google keeps stored interactions for 55 days on the paid tier.
The same request in REST, which is useful for seeing exactly what goes over the wire:
curl --silent --show-error --max-time 900 \
"https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-4-neon",
"input": "List exactly three checks for confirming a new API integration works.",
"store": false,
"generation_config": {
"thinking_level": "low",
"max_output_tokens": 65536
}
}' \
--output neon-response.json
Field names inside generation_config are snake_case in Python, JavaScript and REST for the Interactions API. output_text is a convenience property of the SDK; in the raw REST response the text sits in steps items of type model_output, inside content entries of type text.
The 900-second --max-time follows Google’s migration advice to allow at least 15 minutes for hard prompts. A trivial prompt at low should return much sooner. If the client times out, the server may still have processed (and billed) the request, so don’t fire an automatic retry before checking.
Step 3: Or use generateContent if your client already does
generateContent remains supported for Neon. If your application already parses candidates, changing the model string and thinking config may be all you need. Note the different casing: generateContent REST uses camelCase.
curl --silent --show-error --max-time 900 \
"https://generativelanguage.googleapis.com/v1beta/models/gemini-4-neon:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"role": "user", "parts": [{"text": "List exactly three checks for confirming a new API integration works."}]}],
"generationConfig": {
"thinkingConfig": {"thinkingLevel": "low"},
"maxOutputTokens": 65536
}
}' \
--output neon-response.json
The Python SDK form is:
from google import genai
from google.genai import types
client = genai.Client()
response = client.models.generate_content(
model="gemini-4-neon",
contents="List exactly three checks for confirming a new API integration works.",
config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(thinking_level="low"),
max_output_tokens=65536,
),
)
print(response.text)
print("Thinking tokens:", response.usage_metadata.thoughts_token_count)
The level values are lowercase strings in both forms ("low", "xhigh"), following Google’s thinking guide. Don’t mix the two APIs: generation_config.thinking_level belongs in an Interactions body and generationConfig.thinkingConfig.thinkingLevel in a generateContent body. If you get a 400 after copying code between the two APIs, check the field shape first. Also drop any old thinkingBudget (thinking_budget): it is deprecated on Gemini 4, and sending it together with a thinking level returns a 400.
Choose one API per code path. The Interactions API gives you server-side state (previous_interaction_id) and background execution. With generateContent you manage history yourself and must send prior model turns, including their thought signatures, back unchanged.
Step 4: Check status, text and usage before trusting the call
An HTTP 200 is not enough. An interaction can come back with a status other than completed, and a generateContent candidate can end with MAX_TOKENS after spending its whole budget on thinking. Either can contain no visible text at all. Google’s long decode guide gives the action for each Interactions status:
| Status | What it means | What to do |
|---|---|---|
queued, in_progress | Still running (background calls) | Poll interactions.get with the same id |
completed | Finished | Join the model_output text and read usage |
requires_action | The model asked for a tool call | Run the tool and send the result with this id |
requires_continuation | A foreground hop hit the 65,536 cap with budget left | The SDK continues by default; in REST, send the next hop with previous_interaction_id and continuation_token |
incomplete | All of max_output_tokens was used; text can be empty | Resume or resend with a higher max_output_tokens |
failed | The server couldn’t finish | Retry once; if it fails again, keep the id for support |
cancelled | You cancelled it | Read usage to see what was billed |
On generateContent, the equivalents are finishReason values: STOP is success, MAX_TOKENS means the cap was reached, and CONTINUATION means another hop is needed (the latest SDKs continue automatically).
This checker reads a saved response from either API. It makes no network calls and never retries:
import json
import sys
from pathlib import Path
PENDING = {"queued", "in_progress"}
def check_interaction(p):
status = p.get("status")
if status in PENDING:
raise ValueError(f"Still {status}: poll interactions.get with this id later")
if status != "completed":
raise ValueError(f"Interaction status is {status}, not completed (see the status table)")
text = "".join(
c.get("text", "")
for s in p.get("steps", [])
if s.get("type") == "model_output"
for c in s.get("content", [])
if c.get("type") == "text"
)
u = p.get("usage") or {}
usage = {
"input": u.get("total_input_tokens"),
"cached_input": u.get("total_cached_tokens"),
"output": u.get("total_output_tokens"),
"thinking": u.get("total_thought_tokens"),
"tool_use": u.get("total_tool_use_tokens"),
"total": u.get("total_tokens"),
}
return text, usage
def check_generate_content(p):
cands = p.get("candidates") or []
if not cands:
reason = (p.get("promptFeedback") or {}).get("blockReason")
raise ValueError(f"No candidates (prompt block reason: {reason})")
c = cands[0]
reason = c.get("finishReason")
if reason != "STOP":
raise ValueError(f"finishReason is {reason}, not STOP")
text = "".join(
part.get("text", "")
for part in (c.get("content") or {}).get("parts", [])
if not part.get("thought")
)
u = p.get("usageMetadata") or {}
usage = {
"input": u.get("promptTokenCount"),
"cached_input": u.get("cachedContentTokenCount", 0),
"output": u.get("candidatesTokenCount"),
"thinking": u.get("thoughtsTokenCount"),
"tool_use": u.get("toolUsePromptTokenCount", 0),
"total": u.get("totalTokenCount"),
}
return text, usage
def check(payload):
if "error" in payload:
raise ValueError("API error: " + json.dumps(payload["error"]))
if "candidates" in payload or "promptFeedback" in payload:
text, usage = check_generate_content(payload)
elif "status" in payload or "steps" in payload:
text, usage = check_interaction(payload)
else:
raise ValueError("Unrecognised response shape")
if not text.strip():
raise ValueError("Completed, but no visible text")
return text, usage
if __name__ == "__main__":
path = sys.argv[1] if len(sys.argv) > 1 else "neon-response.json"
payload = json.loads(Path(path).read_text(encoding="utf-8"))
try:
text, usage = check(payload)
except ValueError as exc:
raise SystemExit(str(exc))
print("Usage:", json.dumps(usage))
print(text)
Run python3 check_neon.py neon-response.json. A pass prints a normalised usage line and the visible answer. Then read the answer: three relevant checks, not a refusal or a truncated sentence.
What we tested. We ran the checker exactly as printed above against 15 hand-written fixtures: a completed interaction with text split across two model_output steps and a thought step; the same interaction after a round trip through the google-genai SDK’s Interaction model and model_dump(mode="json"), as Step 2 saves it; in_progress, incomplete, requires_action, requires_continuation, failed and completed-but-empty interactions; an API error body; and generateContent responses ending in STOP (with a thought part to be excluded), MAX_TOKENS, CONTINUATION, MALFORMED_FUNCTION_CALL, a blocked prompt and a thought-only answer. The three well-formed successes passed and the other twelve exited with the expected message. The fixtures follow the documented field names; they are not captured Neon output.
Which usage fields matter for Neon
The usage record is where Neon’s two cost levers show up: thinking and cache hits.
| Meaning | Interactions usage | generateContent usageMetadata |
|---|---|---|
| Input tokens | total_input_tokens | promptTokenCount |
| Cache-hit input | total_cached_tokens | cachedContentTokenCount |
| Visible output | total_output_tokens | candidatesTokenCount |
| Thinking | total_thought_tokens | thoughtsTokenCount |
| Tool-use prompt tokens | total_tool_use_tokens | toolUsePromptTokenCount |
| Total | total_tokens | totalTokenCount |
Field names are from Google’s Interactions and generateContent API references. Google’s reference example (an earlier model, not Neon) shows thinking reported separately from visible output: 49 thought tokens next to 23 output tokens for a one-sentence reply. On Neon, thinking is billed at the $15.00 output rate. Google counts every token the model processes, including thinking and, with grounding, internal system instructions and function declarations. So a short visible answer can still produce a large output charge at high or xhigh. Log thinking next to output for every call; that pair is the first thing to look at when a bill looks wrong.
Step 5: Choose the thinking level per task
Google’s guide describes the four levels this way (paraphrased):
| Level | Google’s description | Typical use |
|---|---|---|
low | Fewest tokens, lowest latency | Fast chat, high-throughput processing, cheap access checks |
medium | Lower token use, faster responses | Interactive coding, UI prototyping, latency-sensitive tool calls |
high (default) | Balanced intelligence and speed | Most complex coding, agentic execution, multimodal knowledge work |
xhigh | Most tokens, deepest reasoning | Hard multi-step engineering, analytical and scientific problems where high falls short |
Google’s recommended method: evaluate your task at all four levels with a high max_output_tokens, so the cap doesn’t cut answers short, then use the lowest level that meets your quality bar. To request xhigh:
interaction = client.interactions.create(
model="gemini-4-neon",
input="Audit this retry queue for race conditions and rewrite the lock logic.",
generation_config={"thinking_level": "xhigh"},
)
Two cautions specific to Neon:
xhighand the 65,536 cap interact. The cap covers thinking plus output. Google’s thinking guide warns thatxhighcan overthink and exhaustmax_output_tokenson simple prompts such as text or JSON extraction. If you seeMAX_TOKENSor anincompleteinteraction with little visible text, look at the task first. For a simple task, lower the level. For a genuinely hard one, keep the level and give it more room with background execution and a largermax_output_tokens(see the background execution section below). Don’t shrinkmax_output_tokensto save money: Google notes that it cuts the answer off and you still pay for the thinking already done.- Google’s cost claims are measured at specific levels. Google’s Neon announcement says that at the default
highlevel Neon pairs a high Artificial Analysis Intelligence Index score with a 32% lower cost per task than Carbon, and that Neon’s highest intelligence score is atxhigh. Google ties the 32% to the AA Intelligence Index but does not state which Carbon thinking level, which Carbon price period or which AA data snapshot it compared against, and the AA numbers we read on November 19, 2026 do not reproduce it; our Neon pricing breakdown shows the comparison. Those are Google-reported benchmark results, not a forecast for your workload. Measure your own task with the usage fields above.
previous_interaction_id carries conversation history only. It does not carry generation_config, tools or system_instruction, so a follow-up turn without thinking_level falls back to Neon’s default high. Resend the level on each turn.
Use implicit caching instead of cachedContents
Neon supports only implicit caching. If you migrate code that creates caches with caches.create or sends cached_content, remove those fields. Google’s caching guide says explicit caching is not supported in the Interactions API or for Gemini 4 models.
Implicit caching runs automatically on prompts of at least 4,096 tokens. A hit is billed at $0.15 per 1M input tokens instead of $3.00, a 95% discount. You can’t force a hit, but Google’s caching guide gives two ways to raise the odds:
- Put large, shared content (system instructions, a repository map, a reference document) at the start of the prompt, and the per-request question at the end.
- Send requests with the same prefix close together in time.
For multi-turn chats and agent loops, Google adds a Gemini 4 rule: the full previous request is cached only if the new request adds at least 2,050 tokens (model output, thoughts and function results count). Smaller additions re-process the last 2,050 tokens of the previous request at the standard input rate. Google says most agent turns exceed that threshold.
Then verify with data rather than assumption: total_cached_tokens (Interactions) or cachedContentTokenCount (generateContent) should be non-zero on the second and later requests that share a long prefix. If it stays at 0, check that the prefix is byte-for-byte identical, including timestamps or request IDs you may be injecting at the top.
Outputs longer than 64K: background execution
A single synchronous Neon response stops at 65,536 tokens of thinking plus output. For a long specification, a large refactor plan or a full test suite, Google recommends background execution:
import time
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-4-neon",
input="Write a complete migration specification and test plan for this service.",
background=True,
generation_config={"max_output_tokens": 262144, "thinking_level": "high"},
)
while interaction.status in ("queued", "in_progress"):
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("Status:", interaction.status)
print("Usage:", interaction.usage)
print(text)
Text arrives in several model_output steps because the server continues in 64K hops, so join all of them (the checker above does the same). A background interaction can run for up to 24 hours; if it ends failed, retry once, as in the status table. Two more details are easy to miss. If you set background without max_output_tokens, the server still stops after 65,536 tokens. And background execution needs storage, so don’t combine it with store=False. The upper bound is 1,048,576 minus your input tokens. Google’s long decode guide covers client-side continuation if you can’t store interactions.
Common Gemini 4 Neon API errors and fixes
Record the endpoint, exact model ID, project, SDK version and the full error body (without the key) before changing anything. Fix the earliest layer that failed.
| Symptom | Likely cause on Neon | Fix |
|---|---|---|
| Access or quota error on a key that works for Hydrogen | Key belongs to a free-tier project; Neon is paid-tier only | Use a key from a project with paid billing active (Step 1) |
| Model not found | Typo, invented suffix such as -preview, or a gateway that doesn’t route Neon | Use gemini-4-neon against generativelanguage.googleapis.com |
400 on thinking_level | minimal sent (rejected on Gemini 4), Interactions and generateContent field shapes mixed, or an old thinkingBudget sent alongside the level | Use low/medium/high/xhigh; match field names to the endpoint; remove thinkingBudget |
| 400 validation error with sampling params | Out-of-range temperature, top_p or top_k | Remove sampling parameters; in-range values are ignored anyway |
| Request fails after migrating cache code | Old cached_content / cachedContents reference (explicit caching unsupported) | Remove it; rely on implicit caching |
MAX_TOKENS, incomplete or empty text | Low max_output_tokens consumed by thinking | Restore 65,536, use background execution for long work, or lower thinking deliberately |
MALFORMED_FUNCTION_CALL | Model told to emit raw-text JSON tool calls with no tools declared | Declare tools with function calling, or use structured output |
| Signature errors in multi-turn tool use | Thought signatures dropped or copied across parallel calls | Use previous_interaction_id, or return prior turns unchanged; see our missing thought signature fix |
| Client timeout on hard prompts | high/xhigh reasoning takes minutes | Raise HTTP timeout to at least 15 minutes or use background execution |
| 429 | Paid-tier rate limits still apply | Reduce concurrency and back off; see our 429 retry guide |
Most rows come straight from Google’s Neon migration checklist. For worked route, quota and response diagnostics on a sibling model, see our Gemini 4 Argon API error walkthrough; the Argon-specific values there (default thinking, levels) don’t apply to Neon. For Carbon, Neon and Hydrogen errors in one place, including empty or truncated answers, see our Gemini 4 Carbon, Neon and Hydrogen error guide.
Can you call Gemini 4 Neon through Ofox?
Not as of November 19, 2026. Ofox’s model list returned Gemini 4 Hydrogen and Argon but not Neon, and the Neon model page path returned 404. Don’t point the code above at an Ofox base URL: the Interactions endpoint and an Ofox key are different systems, and there is no Neon route to reach.
To check again later, look for google/gemini-4-neon in the Ofox model list (GET https://api.ofox.ai/v1/models with your Ofox key) or at ofox.ai/models. If it appears, its model page lists the supported protocols and current price. The request format for Gemini models on Ofox is in the Ofox Gemini API docs. Use those docs for the endpoint and authentication; don’t assume this article’s Google-native code carries over unchanged.
If you need a Gemini 4 model through Ofox today, Gemini 4 Hydrogen is listed and the setup guide covers its Ofox route. For how Neon compares with the rival flagships that Google benchmarks it against, see Gemini 4 Neon vs Claude Opus 5.5 vs GPT-6.2 Sol.
First-call acceptance checklist
Before you call the Neon integration done, save this non-secret record:
- Model ID
gemini-4-neon, endpoint, SDK version and project identifier. - One saved response that passes the checker:
completedorSTOP, non-empty text. - The usage line, with thinking and cached-input tokens recorded separately.
- The
thinking_levelandmax_output_tokensyou sent, written explicitly in code rather than inherited from defaults. - Any error you hit and the change that fixed it.
With that baseline in place, add tools, long documents or background jobs one at a time. When something fails, you’ll know it was the new part.
Related Docs
- Ofox Gemini API documentation: request format for Gemini models that are available on Ofox
- Ofox error handling guide: reading and retrying errors on Ofox routes
- Ofox rate limits: current default limits and how to request more
- Google: What’s new in Gemini 4 Neon: official model guide and migration checklist


