DEV Community

Cover image for How to use Gemini 4 Neon API?
Hassann
Hassann

Posted on Originally published at apidog.com

How to use Gemini 4 Neon API?

The Gemini 4 Neon API uses the model ID gemini-4-neon. You call it with a POST to https://generativelanguage.googleapis.com/v1beta/interactions, your key in the x-goog-api-key header, and model plus input in the JSON body. It runs on the paid tier only, at $3 per million input tokens and $15 per million output tokens, and defaults to the high thinking level.

Try Apidog today

This guide covers what's different about Neon: the paid-tier setup, switching from another Gemini 4 model, outputs longer than 64K tokens, pairing Neon with Hydrogen, and keeping the bill in check. Every field name comes from Google's docs.

What do you need before your first Gemini 4 Neon API call?

You need a Gemini API key on a project with billing, the model ID gemini-4-neon and the Interactions endpoint. Google released Neon on November 18, 2026, as the middle model of the Gemini 4 family, between Hydrogen and Carbon.

Item Value
Model ID gemini-4-neon
Endpoint POST /v1beta/interactions on generativelanguage.googleapis.com
Auth header x-goog-api-key: $GEMINI_API_KEY
APIs Interactions API and generateContent
Thinking levels low, medium, high (default), xhigh
Context window 1,048,576 tokens, shared by input, thinking and output
Output per synchronous hop 65,536 tokens
Long decode Up to 1,048,576 tokens minus your input
Free tier No
Paid price $3.00 / 1M input, $15.00 / 1M output (thinking included)
Cached input $0.15 / 1M via implicit caching

For PDFs, function calling and streaming, the request shapes match our Gemini 4 Hydrogen API guide; swap the model ID.

Gemini 4 Neon API

How do you get a Gemini API key that works with Neon?

Neon isn't on the free tier, so a key alone isn't enough. The project behind it needs billing.

  1. Open the API keys page in Google AI Studio and create a key, or reuse one you already have.
  2. Make sure the key's project is on the paid tier. Google's guide says plainly: "Neon is available on the paid tier only (not on the free tier)."
  3. Export the key: export GEMINI_API_KEY="YOUR_API_KEY". The Google GenAI SDKs read it automatically.
  4. Check your paid-tier rate limits on the rate limits page before you plan a large batch.

How do you send your first Gemini 4 Neon API request?

Send model and input to the Interactions endpoint. This is Google's quickstart shape:

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "model": "gemini-4-neon",
    "input": "Review this Go handler for missing error checks and suggest fixes."
  }'
Enter fullscreen mode Exit fullscreen mode

The same call with the Python SDK (pip install -U google-genai):

from google import genai

client = genai.Client()  # reads GEMINI_API_KEY

interaction = client.interactions.create(
    model="gemini-4-neon",
    input="Review this Go handler for missing error checks and suggest fixes.",
)

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

Read usage on every response while you test: thinking tokens bill at the $15 output rate, so the thought count is where your cost goes.

These snippets follow Google's guide. We didn't run them for this post, so check the response shape against your own first call.

What changes when you switch from Hydrogen or Carbon?

If you already run another Gemini 4 model, switching needs no request schema changes. Change the model string and check three things:

Check Neon Hydrogen Carbon and Argon
Default thinking level high high medium
Highest level xhigh xhigh high
Input / output per 1M $3 / $15 $1.50 / $7.50 See Carbon pricing

Coming from Carbon or Argon, the default jump from medium to high means more thinking tokens on the same prompt. Set thinking_level explicitly if you want the old behavior:

interaction = client.interactions.create(
    model="gemini-4-neon",
    input="Audit this payment retry queue for race conditions.",
    generation_config={"thinking_level": "medium"},
)
Enter fullscreen mode Exit fullscreen mode

Coming from Gemini 3.8 Flash or older, the list is longer. Per Google's migration checklist:

  • Raise low output caps. max_output_tokens covers thinking and answer together. Remove hardcoded caps such as 8,192, or raise them to 65,536, and lower the thinking level if you need to spend less.
  • Drop minimal. Neon rejects it with an error.
  • Remove sampling parameters. The server ignores in-range temperature, top_p and top_k; out-of-range values return a 400.
  • Move off explicit caching. Neon doesn't support cachedContents or caches.create, so remove cached_content fields.
  • Declare tools natively. Prompting for raw JSON tool calls with no declared tools can return MALFORMED_FUNCTION_CALL. Use function calling or structured outputs.

How do you get more than 64K tokens out of Neon?

A synchronous request stops at 65,536 tokens, streaming or not. For longer output, such as a full migration spec plus its test suite, set background to true and raise max_output_tokens above 65,536. Google's servers then keep generating in 64K-token hops until they hit your cap.

Gemini 4 Neon long decode

Start the job and keep its id:

export ID=$(curl -s -X POST "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": "Generate a complete multi-module migration specification and test suite for this service.",
    "background": true,
    "generation_config": {
      "max_output_tokens": 262144,
      "thinking_level": "high"
    }
  }' | jq -r '.id')
Enter fullscreen mode Exit fullscreen mode

Then poll until it finishes and join the text from every hop (Python, with the ID you exported):

import os, time

interaction = client.interactions.get(id=os.environ["ID"])
while interaction.status in ("in_progress", "queued"):
    time.sleep(5)
    interaction = client.interactions.get(id=interaction.id)

text = "".join(
    c.text
    for step in interaction.steps if step.type == "model_output"
    for c in step.content if c.type == "text"
)
Enter fullscreen mode Exit fullscreen mode

Three rules from Google's guide keep this from going wrong:

  1. If you set background without max_output_tokens, the server stops at 65,536 tokens.
  2. The cap can go up to 1,048,576 minus your input tokens. Google suggests 131,072 or 262,144 for long, multi-step work.
  3. Hard prompts can run for several minutes. Use background mode, or set HTTP client timeouts to at least 15 minutes.

If you'd rather not store interactions on Google's side, the long decode guide also documents client-side continuation in the latest SDKs.

How do you pair Neon with Hydrogen?

Use Neon for the judgment and Hydrogen for the volume. Neon plans or reviews a workflow, then you pass its interaction id as previous_interaction_id to a gemini-4-hydrogen call that does a single step. Google's Cloud developer guide shows the pattern:

plan = client.interactions.create(
    model="gemini-4-neon",
    input="Design a 3-step plan to migrate our REST order service to gRPC in Go.",
    store=True,
)

step = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Implement step 1 (.proto service definition) from the plan.",
    previous_interaction_id=plan.id,
)
print(step.output_text)
Enter fullscreen mode Exit fullscreen mode

Gemini 4 Neon as planner, Hydrogen as executor

Every output token Hydrogen writes instead of Neon costs half as much. Our Gemini 4 Hydrogen orchestrator guide walks through the same loop with Carbon as the planner.

How do you keep Gemini 4 Neon API costs down?

Four levers, in the order they usually pay off:

  1. Pick the lowest thinking level that passes. Google's advice is to run your evaluations at all four levels with a high max_output_tokens, then pick the lowest thinking_level that meets your quality bar.
  2. Reuse long prompts. Implicit caching runs by default on prompts of at least 4,096 tokens and cuts cached input by 95%, from $3.00 to $0.15 per million. Keep the long, stable part of your prompt (system text, docs, schemas) at the front.
  3. Hand execution to Hydrogen. See the pairing pattern above.
  4. Count everything. Google bills every token the model processes, including thinking tokens and the internal instructions added when you use grounding. Grounding with Google Search is also billed per query.

A quick sanity check: a call with 20,000 input tokens and 8,000 output tokens (thinking included) costs $0.06 for input and $0.12 for output, so $0.18 at list price.

Let your coding agent compare Neon and Hydrogen with Apidog CLI

Is Neon worth twice Hydrogen's price on your prompts? Let your coding agent (Claude Code, Codex, Cursor) build one test case and run it against both models with Apidog CLI.

Set it up once:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted
Enter fullscreen mode Exit fullscreen mode

Then give your agent one prompt:

In Apidog project <projectId>, create an environment "gemini" with base URL
https://generativelanguage.googleapis.com and variables GEMINI_API_KEY,
MODEL (default "gemini-4-hydrogen") and THINKING (default "high"). Add an
endpoint for POST /v1beta/interactions with the x-goog-api-key header from
GEMINI_API_KEY. Create a test case that sends model {{MODEL}}, our code-review
prompt and generation_config.thinking_level {{THINKING}}, and asserts: HTTP 200,
status is "completed", a non-empty model_output step, and usage.total_tokens
exists. Run it for gemini-4-hydrogen and gemini-4-neon, then compare
usage.total_thought_tokens and usage.total_output_tokens.
Enter fullscreen mode Exit fullscreen mode

The agent reads each payload schema and validates its JSON before it writes anything:

apidog environment create gemini --project <projectId> --base-url https://generativelanguage.googleapis.com
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "MODEL=gemini-4-hydrogen" -r cli,json
apidog run --test-case <caseId> --project <projectId> -e <envId> --env-var "MODEL=gemini-4-neon" -r cli,json
Enter fullscreen mode Exit fullscreen mode

Multiply each run's tokens by the model's price and you have a real cost per task for your prompt, not a launch-post average. Add --upload-report to view the run in the Apidog app, or swap -r cli,json for -r junit to put the same check in CI. The Apidog CLI CI/CD guide shows the pipeline, and Apidog CLI in Claude Code covers the agent setup. Apidog's Free plan covers up to 4 users.

FAQ

What is the Gemini 4 Neon model ID? gemini-4-neon. It works with both the Interactions API and generateContent.

Is the Gemini 4 Neon API free? No. Neon is on the paid tier of the Gemini API only, at $3 per million input tokens and $15 per million output tokens. Google AI Pro and Ultra subscribers can try it in the AI Studio chat.

Does my Hydrogen code work with Neon? Yes. Google says switching between Gemini 4 models needs no request schema changes. Update the model string, then decide whether you want the default high thinking level.

What's the maximum output of the Gemini 4 Neon API? 65,536 tokens per synchronous request. With background set to true and a higher max_output_tokens, Neon can generate up to the 1,048,576-token window minus your input.

Does Gemini 4 Neon support temperature? No. The server ignores in-range temperature, top_p and top_k values and returns a 400 for out-of-range ones. Use thinking_level to trade quality for speed and cost.

Does Neon support explicit context caching? No. Remove cached_content from your requests. Implicit caching still applies automatically to prompts of 4,096 tokens or more, at a 95% discount on cached input.

Top comments (0)