Build a long-context research analyst with Gemini 4 Neon: thinking levels, structured output, and long decode, end to end
Google's new mid-tier model costs $3/$15 per million tokens, thinks at four levels, and reads a million tokens of PDFs, charts, and spreadsheets in one call. This tutorial builds a complete research analyst on the Interactions API — verified call by call against the Python SDK — and prices every run to the cent.
- What it is: Gemini 4 Neon, released November 18, 2026. API model ID
gemini-4-neon, 1M-token unified context, up to 65,536 output tokens per synchronous request (up to 1M with long decode). - Verified here: Every SDK call was checked against google-genai 3.6.1 with a mocked transport (no API key was available in the verification sandbox, so the model was not called live): the request shapes, the response parsing, the step walk, the cost math, and the long-decode poll loop. Token counts shown are from the scripted verification run — yours will differ.
- The price: $3.00 per million input tokens, $15.00 per million output tokens — thinking tokens bill as output. Cached input $0.15 per million (implicit caching only; no explicit context caching). Paid tier only — Neon has no free tier.
- Thinking is the cost dial: low, medium, high (default), xhigh. Higher levels spend more tokens per task — the per-token price does not change.
- What it can't do: image generation, audio generation, and the Live API are not supported. Output is text only.

Google released Gemini 4 Neon on November 18, and it is the most useful Gemini model most developers will ever call for analytical work: a mid-tier reasoning model that sits between the fast Hydrogen and the frontier Carbon, priced at $3 per million input tokens and $15 per million output tokens, with a million-token context window. Google's own numbers put it at 61 on the Artificial Analysis Intelligence Index at its xhigh thinking level — third overall, behind larger, slower models — and first on the Artificial Analysis Coding Agent Index at 58.6, with 65.2% on Terminal-Bench 4.1. Treat those as the company's numbers, not independent verification. The price, the API rules, and the capabilities are in the documentation — and the API rules are the reason this tutorial exists.
Neon changes how you call Gemini in one big way: the current docs lead with a new Interactions API — one input, one generation config, typed steps back — and the model is built for long, tool-heavy work: a unified 1M-token context, thinking at four levels, structured output, code execution, file search, and long decode up to a million output tokens. This tutorial builds the workflow Neon is designed for: a research analyst that reads an earnings-release PDF and a revenue chart, returns a structured brief with every figure sourced, recomputes the growth numbers with real code instead of trusting the model's arithmetic, and writes the full report as a background job. By the end you will have the whole analyst in one file — about 220 lines — and you will know exactly what each thinking level costs, when the 65,536-token output cap bites, and when Neon is the wrong model.
What you'll need#
- Python 3.11 or newer. The examples use the official
google-genaiPython SDK, version 3.6.1 at time of writing (it requires Python 3.11+). Long decode's client-side continuation needs SDK 2.34.0 or newer; 3.6.1 is well past that. - A Gemini API key from Google AI Studio at aistudio.google.com, on the paid tier. Neon is not available on the free tier — Hydrogen is the only Gemini 4 model with one. The SDK reads
GEMINI_API_KEYfrom the environment. - About a dollar of API credit. At Neon's standard rates, a 200,000-token document pack analyzed once costs about $0.90; the whole tutorial's calls come to a few dollars at most.
- A scratch directory with an earnings-release PDF and a chart image. Any real ones will do — the verification run used a one-page sample PDF and a bar chart.
Step 1 — Install and verify#
Create a project folder and a virtual environment, then install the SDK and pydantic. Every snippet in this tutorial was checked against the installed packages before publication — including the four thinking levels and the Interactions API calls, which did not exist on older SDK versions.
mkdir neon-analyst
cd neon-analyst
python3 -m venv .venv
source .venv/bin/activate
pip install google-genai==3.6.1 pydantic
Confirm the install and that the SDK knows the model. The Models API is the fastest way to prove your key and the model ID are both valid — it returns the model's display name and token limits without spending a token on generation:
pip show google-genai | grep Version
python3 -c "import google.genai; print(google.genai.__version__)"
from google import genai
client = genai.Client() # reads GEMINI_API_KEY from the environment
model = client.models.get(model="gemini-4-neon")
print(model.name, "·", model.display_name, "·",
model.input_token_limit, "in ·", model.output_token_limit, "out")
Expected output:
models/gemini-4-neon · Gemini 4 Neon · 1048576 in · 65536 out
The two limits shape everything else in this tutorial: one shared window of 1,048,576 tokens for input, thinking, and output together, and a 65,536-token cap on a single synchronous response. If the get call fails, check the key first: a wrong or missing key returns a 401, while a wrong model ID returns a 404. Note the method name — it is models.get, and the model ID is the bare gemini-4-neon, with no models/ prefix and no version suffix.
Step 2 — Your first Neon call#
The smallest correct request on the Interactions API has two fields: the model and the input. There is no contents array and no config object to build — the thinking level and the output cap live in one generation_config dict, which you will meet in the next step. Here is the whole call, plus the two helpers this tutorial uses on every step: cost_of, which prices an interaction from its usage object, and show_usage, which prints the four numbers that matter.
from google import genai
MODEL = "gemini-4-neon"
# USD per million tokens, Gemini 4 Neon standard tier (Google pricing page).
PRICES = {"input": 3.00, "output": 15.00, "cache_read": 0.15}
def cost_of(usage) -> float:
"""USD cost of one interaction, from its usage object."""
fresh = usage.total_input_tokens - usage.total_cached_tokens
return (
fresh * PRICES["input"]
+ usage.total_cached_tokens * PRICES["cache_read"]
+ (usage.total_output_tokens + usage.total_thought_tokens)
* PRICES["output"]
) / 1_000_000
def show_usage(tag, interaction):
u = interaction.usage
print(
f"{tag}: {u.total_input_tokens} in / "
f"{u.total_output_tokens} visible out / "
f"{u.total_thought_tokens} thinking / "
f"${cost_of(u):.4f}"
)
client = genai.Client() # reads GEMINI_API_KEY from the environment
interaction = client.interactions.create(
model=MODEL,
input="In one paragraph, what is a thinking level?",
)
print(interaction.output_text)
show_usage("first call", interaction)
Expected output — the usage line is from the scripted verification run, so your counts will differ:
first call: 412 in / 2600 visible out / 3400 thinking / $0.0912
Three fields on the usage object do the pricing work, and they are the reason this tutorial prints them after every call. total_input_tokens is everything you sent, total_output_tokens is the visible reply, and total_thought_tokens is the reasoning you never see — billed at the $15 output rate, not the $3 input rate. total_cached_tokens is the share of the input served from implicit cache at $0.15. Add them up and the first call cost nine cents in the verification run — most of it thinking, which is the pattern for the rest of this tutorial.
Two things are different from requests you may have written for Gemini 2.5 or 3.8 Flash. First, the call posts to /v1/interactions with the model in the body, not in the URL — the SDK handles that, but if you log requests (as the verification harness did), expect the new path. Second, there is no temperature, top_p, or top_k anywhere in the config: on Gemini 4 those sampling knobs are gone — in-range values are ignored and out-of-range values return a 400. If a reply feels too random or too flat, change the thinking level or the wording. There is no sampling knob left to turn.
Step 3 — Thinking levels: the one dial that matters#
Thinking level is the single most misunderstood parameter on Neon, because it looks like a quality setting and behaves like a budget. It controls how many tokens the model spends reasoning before it answers — and every one of those tokens bills at the $15 output rate. The per-token price never changes; the level changes how many tokens the model uses. Four levels are documented for Neon, and Google's guidance is specific about where to start:
| Level | What it is for | Default anywhere? |
|---|---|---|
low | Fewest thinking tokens, lowest latency. Routing, classification, short summaries, extraction. | No |
medium | Balances reasoning quality and latency. Interactive work, responsive chat, drafting. | No — but the default on Argon and Carbon |
high | Deep reasoning, multi-step problem solving, multi-turn tool use. Agent runs, hard analysis. | API default on Neon — start here |
xhigh | Maximum thinking capacity, for the hardest math, science, and long-horizon work. | No — Neon's highest intelligence score (61 on the AA Index) is measured here |
The loop below runs the same question at all four levels and prints the usage each time. The question is deliberately easy — a division with a checkable answer — because the point is the cost curve, not the answer:
LEVELS = ("low", "medium", "high", "xhigh")
def thinking_levels(client, question):
for level in LEVELS:
interaction = client.interactions.create(
model=MODEL,
input=question,
generation_config={
"thinking_level": level,
"max_output_tokens": 8192,
},
)
show_usage(level, interaction)
print(" answer:", interaction.output_text.strip()[:120])
thinking_levels(
client,
"A company reports Q3 revenue of $412M, up 18% year over year. "
"What was Q3 revenue a year ago, to the nearest $0.1M? "
"Show the arithmetic.",
)
Expected output — token counts from the scripted verification run:
low: 412 in / 900 visible out / 300 thinking / $0.0192
answer: Q3 revenue a year ago was $349.2M (412 / 1.18).
medium: 412 in / 1800 visible out / 1400 thinking / $0.0492
answer: Q3 revenue a year ago was $349.2M (412 / 1.18).
high: 412 in / 2600 visible out / 3400 thinking / $0.0912
answer: Q3 revenue a year ago was $349.2M (412 / 1.18).
xhigh: 412 in / 4800 visible out / 9100 thinking / $0.2097
answer: Q3 revenue a year ago was $349.2M (412 / 1.18).
Two lessons. First, the spread: the same question costs eleven times more at xhigh than at low ($0.2097 against $0.0192), and the thinking tokens grow far faster than the visible reply — 300 at low, 9,100 at xhigh. Second, the answer is identical at every level, because the question is easy. That is the whole discipline of the dial: low is enough for arithmetic, extraction, and routing, and every level above low is money spent on a harder question than the one you asked. Google's advice is to start at high for most complex tasks and reserve xhigh for problems where high is not enough — and to set the level explicitly on every request, even when you want the default. A default you did not choose is a default you will forget.
One more detail worth recording: the SDK's type also accepts a minimal level, but the model page lists only low, medium, high, and xhigh as supported for Neon. Use one of the four. And remember the cap: the 65,536-token output limit covers thinking and reply together, so a deep level with a low max_output_tokens can spend the whole budget on thought and return no answer at all. Set max_output_tokens generously on hard questions — Step 7 shows how far it goes.

Step 4 — Structured output: make the brief machine-readable#
A paragraph is a dead end for an analyst workflow — the brief has to feed the next step, and the next step is code. Structured output makes the model return JSON that matches a schema you define, so the figures come back as numbers with sources instead of sentences you have to parse. The schema below is the whole contract of the analyst: a verdict, findings, figures with sources, risks, and a confidence score.
from pydantic import BaseModel, Field
class Figure(BaseModel):
label: str = Field(description="What the number measures.")
value: float
unit: str = Field(description="e.g. USD millions, percent, headcount.")
source: str = Field(description="Where in the document it came from.")
class AnalystBrief(BaseModel):
verdict: str = Field(description="One-sentence bottom line.")
key_findings: list[str]
figures: list[Figure]
risks: list[str]
confidence: float = Field(ge=0.0, le=1.0)
The call adds one argument — response_format — carrying the schema as JSON. The docs' own recipe example passes a pydantic schema the same way, and the SDK sends it as-is, including the $defs block pydantic generates for the nested Figure model:
import json
def structured_brief(client, text):
interaction = client.interactions.create(
model=MODEL,
input=(
"Write an analyst brief for the document below. "
"Extract every figure with its source, list the risks, "
"and give a one-sentence verdict.\n\n" + text
),
generation_config={"thinking_level": "high"},
response_format={
"type": "text",
"mime_type": "application/json",
"schema": AnalystBrief.model_json_schema(),
},
)
brief = AnalystBrief.model_validate_json(interaction.output_text)
print(json.dumps(brief.model_dump(), indent=2))
show_usage("structured brief", interaction)
return brief
Expected output — the brief from the scripted verification run:
{
"verdict": "ACME grew 18% year over year with margins intact.",
"key_findings": ["Revenue up 18% YoY", "Margins flat at 41%"],
"figures": [
{"label": "Q3 revenue", "value": 412.0, "unit": "USD millions",
"source": "p. 2, revenue table"},
{"label": "Q3 revenue, prior year", "value": 349.2,
"unit": "USD millions", "source": "p. 2, revenue table"}
],
"risks": ["Customer concentration in the top account"],
"confidence": 0.85
}
The validation line is not optional decoration. model_validate_json raises if the model returns anything that is not a valid brief — a missing field, a string where a number belongs — and a raise you can see beats a bad number that flows into a report. Keep schemas inside the constructs the docs demonstrate: nested objects, arrays, optional fields, enums. If the model keeps failing validation, simplify the schema before you blame the model.
Step 5 — Read a PDF and a chart in one call#
Neon's input side is where the million-token context earns its keep: text, image, video, audio, and PDF in a single request. The call below sends the earnings release as an inline document and the revenue chart as an image, and asks for the same AnalystBrief schema back — one call, three modalities, figures sourced to a page or a chart label.
import base64
from pathlib import Path
def read_documents(client, pdf_path, chart_path):
pdf_b64 = base64.b64encode(Path(pdf_path).read_bytes()).decode("utf-8")
chart_b64 = base64.b64encode(Path(chart_path).read_bytes()).decode("utf-8")
interaction = client.interactions.create(
model=MODEL,
input=[
{
"type": "text",
"text": (
"Extract an analyst brief from the attached earnings "
"release PDF and revenue chart. Return JSON matching "
"the schema, with every figure sourced to a page or "
"chart label."
),
},
{
"type": "document",
"data": pdf_b64,
"mime_type": "application/pdf",
},
{
"type": "image",
"data": chart_b64,
"mime_type": "image/png",
},
],
generation_config={"thinking_level": "high"},
response_format={
"type": "text",
"mime_type": "application/json",
"schema": AnalystBrief.model_json_schema(),
},
)
brief = AnalystBrief.model_validate_json(interaction.output_text)
show_usage("document brief", interaction)
return brief
Inline files have a size limit — 50MB for PDFs — and the same input shape accepts a file URI from the File API or Cloud Storage for anything larger or reused across calls (files up to 2GB through the File API). For this tutorial, inline base64 is the right call: the documents are small, the code has no upload step, and the request is self-contained. Expected output from the verification run: document brief: 5200 in / 800 visible out / 2400 thinking / $0.0636 — six cents to read a document and a chart and return a validated brief. Note the input token count is the document itself: a dense 200,000-token pack would cost $0.60 before the model writes a word, which is why Step 8 prices the input separately.
Step 6 — Verify the numbers with code execution#
A model that reads a table can still mis-add it. The brief's growth rates are claims until something recomputes them, and the cheapest something is the model's own code execution tool: it writes Python, runs it, and reads the result — in the same interaction, with the code and the output visible as typed steps.
def verify_figures(client, brief):
"""Recompute the brief's growth figures with code execution."""
lines = "\n".join(
f"- {f.label}: {f.value} {f.unit} ({f.source})"
for f in brief.figures
)
interaction = client.interactions.create(
model=MODEL,
input=(
"These figures came from an earnings release. Generate and "
"run Python code to recompute the year-over-year growth rate "
"for each revenue figure that has a prior-year value, and "
"flag any figure that does not reconcile.\n\n" + lines
),
tools=[{"type": "code_execution"}],
)
for step in interaction.steps or []:
if step.type == "model_output":
for block in step.content:
if block.type == "text":
print(block.text)
elif step.type == "code_execution_call":
print("--- code the model ran ---")
print(step.arguments.code)
elif step.type == "code_execution_result":
print("--- result ---")
print(step.result)
show_usage("code execution", interaction)
return interaction
Expected output from the scripted verification run:
--- code the model ran ---
print(412/349.2 - 1)
--- result ---
0.1799...
Recomputed growth is 18.0%. All figures reconcile.
code execution: 1200 in / 900 visible out / 1500 thinking / $0.0396
The walk over interaction.steps is the part to copy exactly: model_output steps carry the prose, code_execution_call steps carry the code in step.arguments.code, and code_execution_result steps carry the output in step.result. Four cents to check the arithmetic — and the check is worth more than the brief, because a wrong growth rate in a report is worse than no growth rate at all. Two limits: code execution runs Python only, and the model can only verify what you give it — if a figure has no prior-year value in the brief, there is nothing to recompute, and the model should say so rather than invent one.
Step 7 — Long decode: write the full report#
The brief is a page; the deliverable is a report. The problem is the 65,536-token cap: a single synchronous response stops there, and thinking counts against the same budget. Long decode raises max_output_tokens past 64K — up to the 1M-token unified window — by splitting generation into hops of up to 64K tokens on Neon and continuing from where the previous hop stopped. The easiest way to run it is background execution: the servers run every hop, and you poll until the interaction completes.
import time
def long_report(client, brief):
"""Write the full report as a background interaction (long decode)."""
interaction = client.interactions.create(
model=MODEL,
input=(
"Write a complete analyst report from this brief: executive "
"summary, segment-by-segment analysis, risk section, and "
"appendix with every figure and its source. Be thorough; "
"this is the long-form deliverable.\n\n"
+ brief.model_dump_json(indent=2)
),
background=True,
generation_config={
"thinking_level": "high",
"max_output_tokens": 262144,
},
)
while interaction.status in ("in_progress", "queued"):
time.sleep(5)
interaction = client.interactions.get(id=interaction.id)
text = "".join(
block.text
for step in interaction.steps or []
if step.type == "model_output"
for block in step.content
if block.type == "text"
)
print(f"report: {len(text)} characters, status {interaction.status}")
show_usage("long report", interaction)
return text
Expected output from the scripted verification run:
report: 9018 characters, status completed
long report: 5000 in / 30000 visible out / 20000 thinking / $0.7650
Three details from the docs that save debugging time. First, always set max_output_tokens above 65,536 for long decode — the docs warn that a low value, such as 8,192, stops the model before it finishes thinking. Second, poll with interactions.get until the status leaves in_progress, then join the model_output steps — the background example in the docs does exactly this, because the server runs every hop and the completed interaction carries the combined output. (If you switch to client-side continuation instead, save the response from create: there, get returns only the last hop.) Third, background execution runs for up to 24 hours and needs stored interactions (store: true, the SDK default) — if you disable storage, you lose the ability to poll. The scripted run above cost $0.77 for 50,000 output tokens; a real long report at xhigh will cost more, and you will see it in the thinking count before you see it anywhere else.
Step 8 — What a run actually costs#
Neon's price card is simple — $3 per million input tokens, $15 per million output tokens, flat across the whole 1M-token window — but the bill is not, because three different token counts feed into it. The cost_of helper in Step 2 reads them all from the usage object: fresh input at $3.00, cached input at $0.15, and visible output plus thinking at $15.00. Work it through once by hand, for a run with a 200,000-token document pack, 8,000 visible output tokens, and 12,000 thinking tokens:
| Token bucket | Tokens | Rate per MTok | Cost |
|---|---|---|---|
| Fresh input | 200,000 | $3.00 | $0.6000 |
| Visible output | 8,000 | $15.00 | $0.1200 |
| Thinking | 12,000 | $15.00 | $0.1800 |
| Total | 220,000 | — | $0.9000 |

Two lessons hide in that table. The first is the cache: Neon supports implicit caching only — no explicit context caching — and it discounts cache hits by 95% to $0.15 per million. Run the same documents a second time and the input line falls from $0.60 to $0.03, bringing the same analysis to $0.33. The second lesson is the thinking: a third of the output tokens here were reasoning, and at xhigh that share grows fast. The level is the cost decision — which is why the loop prints the thinking count on every run.
Two more rates for the budget-conscious. The Batch and Flex tiers halve both prices to $1.50 and $7.50 per million tokens, for work that can wait or flex. And Priority — $5.40 and $27.00 — buys speed, not savings. There is no free tier to fall back on: every token Neon processes is counted and billed, including thinking tokens.
Which approach should you use?#
Three routes reach the same model, and the right one depends on what you are building rather than what you prefer:
| Route | Use it when | You give up |
|---|---|---|
| Interactions API (this tutorial) | You want multi-step, tool-using work without writing the loop, and long decode as a background job. | Fine-grained control over history and retries; the platform builds requests for you. |
| Raw GenerateContent API | You need exact control over history, tools, and token accounting — a product, a harness, an eval. | Convenience: you own the loop, the retries, and the continuation hops. |
| Google Antigravity | A human is driving: interactive coding, with Neon as the Orchestrator directing parallel Hydrogen subagents in one session. | Programmatic control and per-request cost accounting. Needs a paid Pro or Ultra subscription. |
The model choice is a separate question, and Google's own ladder answers it. Neon is the middle — deeper than Hydrogen, cheaper than Carbon — and the deciding number is cost per task, not price per token:
| Model | Context / max output | Price per MTok in / out | Thinking default / cap | Reach for it when |
|---|---|---|---|---|
| Gemini 4 Hydrogen | 1M / 65K | $1.50 / $7.50 | high / xhigh | Everyday coding, agent runs, tool use. Start here. Free tier. |
| Gemini 4 Neon | 1M / 65K | $3.00 / $15.00 | high / xhigh | Complex analysis, research, long agent work. This tutorial. |
| Gemini 4 Argon | 1M / 65K | $2 / $10 until Nov 30, then $4 / $20 | medium / high | Harder reasoning where Neon falls short. No free tier. |
| Gemini 4 Carbon | 1M / 65K | $2 / $10 until Nov 30, then $4 / $20 | medium / high | The hardest long-horizon work; the planner in a Carbon-plus-Hydrogen pair. |
Google's own cost-per-task claim makes the point: at its default high level, Neon pairs a high Artificial Analysis score with a 32% lower cost per task than Carbon. Measure cost per task on your own workload before you standardise: run the same analysis at two thinking levels, read the usage objects, and let the bill decide. Note the Argon and Carbon prices rise on December 1 — after that date Neon is cheaper than both per token, not just per task.
The takeaway#
Gemini 4 Neon is not a cheaper Carbon — it is a different contract. Thinking is a four-level dial, sampling knobs are gone, thinking bills as output, the output cap is 65,536 tokens unless you ask for long decode, and the usage object is the only honest record of what a run cost. In exchange you get a model that reads a million tokens of PDFs, charts, and spreadsheets in one call, returns structured briefs you can feed to code, verifies its own arithmetic, and writes the long report in the background.
The analyst in this tutorial is the whole contract in one file: thinking set explicitly, documents inlined and sourced, figures validated against a schema, numbers recomputed with code execution, the long report behind a background poll, and the usage object read after every call. Start at high, drop to medium for interactive work, measure cost per task before you touch xhigh, and never let a growth rate into a report that code has not recomputed. Do that, and Neon is the cheapest way to finish the analytical work the frontier models are too expensive to touch.
Sources#
- Google — Introducing Gemini 4 Neon (November 18, 2026) — the launch announcement: $3/$15 pricing, the Artificial Analysis Intelligence Index score of 61 at xhigh, the Coding Agent Index lead at 58.6, Terminal-Bench 4.1 at 65.2%, the 32%-lower-cost-per-task claim, and the Antigravity Orchestrator pattern. All benchmark figures in this tutorial are Google's own, vendor-reported numbers.
- Google AI Studio — Gemini 4 Neon model documentation — the model ID, the 1M-token context, the 65,536-token default output cap, the capability list, and the thinking levels low, medium, high, xhigh.
- Google AI Studio — Gemini Developer API pricing — Neon Standard, Batch, Flex, and Priority rates, the $0.15 cached-input rate, implicit caching only, and no free tier; Carbon and Argon at $2/$10 through November 30, $4/$20 from December 1.
- Google AI Studio — Thinking, Long decode, Structured outputs, Code execution, File input methods — the API shapes used in Steps 2–7: the Interactions API, thinking levels, background long decode, the response_format schema, the code execution tool, and inline document input.
- AI Frontier Post — Google releases Gemini 4 Neon, the mid-tier model its billing catalog leaked this morning — the release itself, covered earlier today.