Skip to main content

Google Gemini

Nedura supports Google Gemini as a native provider using the Google AI Studio / Gemini API — not the OpenAI-compatible endpoint. This lets Nedura translate its internal OpenAI-shaped message and tool loop into Gemini's native generateContent API while preserving tool calling, streaming, multimodal inputs, and Gemini-specific response metadata.

Prerequisites​

  • Google AI Studio API key — create one at aistudio.google.com/apikey
  • Billing-enabled Google Cloud project — recommended for agent use. Gemini's free tier is too small for long-running agent sessions because Nedura may make several model calls per user turn.
  • Nedura installed — no extra Python package is required for the native Gemini provider.
API key path

Set GOOGLE_API_KEY or GEMINI_API_KEY. Nedura checks both names for the gemini provider.

Quick Start​

# Add your Gemini API key
echo "GOOGLE_API_KEY=..." >> ~/.nedura/.env

# Select Gemini as your provider
nedura model
# → Choose "More providers..." → "Google AI Studio"
# → Nedura checks your key tier and shows Gemini models
# → Select a model

# Start chatting
nedura chat

If you prefer direct config editing, use the native Gemini API base URL:

model:
  default: gemini-3.7-flash
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

Configuration​

After running nedura model, your ~/.nedura/config.yaml will contain:

model:
  default: gemini-3.7-flash
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

And in ~/.nedura/.env:

GOOGLE_API_KEY=...

Native Gemini API​

The recommended endpoint is:

https://generativelanguage.googleapis.com/v1beta

Nedura detects this endpoint and creates its native Gemini adapter. Internally, Nedura still keeps the agent loop in OpenAI-shaped messages, then translates each request to Gemini's native schema:

  • messages[] → Gemini contents[]
  • system prompts → Gemini systemInstruction
  • tool schemas → Gemini functionDeclarations
  • tool results → Gemini functionResponse parts
  • streaming responses → OpenAI-shaped stream chunks for the Nedura loop

Tool parameter type arrays such as "type": ["number", "null"] are translated into Gemini's scalar type plus nullable form. Multi-type unions keep every alternative through anyOf, including nested properties and array items. This happens automatically; no MCP server or provider configuration change is needed.

Gemini 3 thought signatures

For Gemini 3 tool use, Nedura preserves the thoughtSignature values attached to function-call parts and replays them on the next tool turn. That covers the validation-critical path for multi-step agent workflows.

Gemini 3 may also attach thought signatures to other response parts. Nedura's native adapter is optimized for agent tool loops today, so it does not yet replay every non-tool-call signature with full part-level fidelity.

Prefer the Native Endpoint​

Google also exposes an OpenAI-compatible endpoint:

https://generativelanguage.googleapis.com/v1beta/openai/

For Nedura agent sessions, prefer the native Gemini endpoint above. Nedura includes a native Gemini adapter so it can map multi-turn tool use, tool-call results, streaming, multimodal inputs, and Gemini response metadata directly onto Gemini's generateContent API. The OpenAI-compatible endpoint is still useful when you specifically need OpenAI API compatibility.

If you previously set GEMINI_BASE_URL to the /openai URL, remove it or change it:

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

Host-root base URLs on the Google host are normalized automatically: if the URL doesn't end with an API version segment (v1beta, v1alpha, v1, ...), Nedura appends /v1beta for you, so GEMINI_BASE_URL=https://generativelanguage.googleapis.com works the same as spelling out the /v1beta suffix. The same normalization applies to the Gemini TTS base URL (tts.gemini.base_url). Chat requests only take the native Gemini path when the base URL points at generativelanguage.googleapis.com or the Vertex AI express host below; a proxy on another host is treated as an OpenAI-compatible endpoint, so configure it with its /openai-style URL.

Vertex AI Express Mode Keys​

Google now issues AQ.…-prefixed keys for both Google AI Studio and Vertex AI express mode (the legacy AIza… Studio format is being phased out), so a key's prefix no longer identifies its surface. Nedura never reroutes by key shape: the configured base URL decides the surface. Set GEMINI_API_KEY and leave GEMINI_BASE_URL unset for the default AI Studio host; set GEMINI_BASE_URL to https://aiplatform.googleapis.com (with or without /v1beta1) for a Vertex AI express-mode key, and Nedura completes it to the publishers/google form. Each surface only accepts its own keys — a 403 PERMISSION_DENIED usually means the key/host pairing is crossed, and Nedura appends guidance naming the other surface. A base URL on any other host (a proxy) is never rewritten. Express keys are separate from the OAuth-based Vertex AI provider, which needs no API key.

Models served only in the global location (Gemini 4 Argon) are not reachable on the bare express host, which routes to us-central1. For those, set the base URL to the project-scoped form, https://aiplatform.googleapis.com/v1beta1/projects/<project>/locations/global, and Nedura completes it to …/publishers/google the same way.

Upgrade note for existing express-key users

Earlier Nedura releases detected the AQ. prefix and rerouted such keys to aiplatform.googleapis.com automatically, so the documented setup was "set GEMINI_API_KEY to the express key and leave GEMINI_BASE_URL unset". That automatic reroute is gone: with GEMINI_BASE_URL unset, every request — chat, nedura doctor, TTS — now goes to the AI Studio host and a Vertex express key gets 403 PERMISSION_DENIED there. Add GEMINI_BASE_URL=https://aiplatform.googleapis.com to ~/.nedura/.env (or set base_url on the provider) once and restart.

Available Models​

The nedura model picker shows Gemini models maintained in Nedura's provider registry. Common choices include:

ModelIDNotes
Gemini 4 Argongemini-4-argonFlagship reasoning model; shared 1M input+output window, long decode up to 1M output tokens
Gemini 3.8 Flashgemini-3.8-flashMost capable Flash model for long-horizon agentic and coding work
Gemini 3.7 Flashgemini-3.7-flashRecommended default balance of speed, capability, and multimodal understanding
Gemini 3.1 Pro Previewgemini-3.1-pro-previewMost capable reasoning, math, and coding model
Gemini 3.5 Flash Litegemini-3.5-flash-liteFastest and lowest-cost option for lightweight tasks
Gemini 2.5 Flashgemini-2.5-flashPrevious generation fast model with thinking capabilities
Gemini 2.5 Progemini-2.5-proPrevious generation complex reasoning model

Model availability changes over time. If a model disappears or is not enabled for your key, run nedura model again and pick one from the current list.

Model IDs

Use Gemini's native model IDs such as gemini-3.7-flash, not OpenRouter-style IDs like google/gemini-3.7-flash, when provider: gemini.

Gemini 4 Argon: Reasoning Effort and Long Decode​

Gemini 4 Argon always thinks; Nedura maps the reasoning effort (/reasoning, agent.reasoning_effort) onto its thinkingLevel:

Nedura effortthinkingLevelTotal output budget
none, minimal, lowlow (thoughts hidden for none)Per-request cap
medium (Google's default)mediumPer-request cap
highhighPer-request cap
xhighhigh262,144 tokens (long decode)
max, ultrahigh1,048,576 tokens minus the input (long decode)

Without long decode a single request stops at 65,536 output tokens when streaming (32,768 non-streaming), thinking included. With xhigh or max, Nedura raises maxOutputTokens and, when a request reaches the per-request cap with budget left (finishReason: CONTINUATION), resends the same request with Google's continuationToken until the model finishes. The hops are joined into one reply.

Usage across hops is reported the way Google bills it: every hop re-reads the prompt plus the output so far, so the summed input count is far larger than the real context. Nedura prices the summed counts but feeds context compaction and the context meter the first hop's prompt size, so a long-decode turn does not trigger an early compaction. Long decode runs only on the native endpoints (AI Studio and Vertex AI express); Google's /openai compatibility endpoint, OpenRouter and the OAuth Vertex AI provider stop at the per-request cap.

Latest Aliases​

Google publishes moving aliases for the Pro and Flash Gemini families. gemini-pro-latest and gemini-flash-latest are useful when you want Google to advance the model automatically without changing your Nedura config. Note that your usage charges may be affected if newer models introduce different rates.

AliasCurrently tracksNotes
gemini-pro-latestLatest Gemini Pro modelBest when you want Google's current Pro default
gemini-flash-latestLatest Gemini Flash modelBest when you want Google's current Flash default
model:
  default: gemini-pro-latest
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

If you need strict reproducibility, prefer explicit model IDs such as gemini-3.1-pro-preview or gemini-3.7-flash.

Gemma via the Gemini API​

Google also exposes Gemma models through the Gemini API. Nedura recognizes these as Google models, but hides very low-throughput Gemma entries from the default model picker so new users do not accidentally select an evaluation-tier model for a long-running agent session.

Useful evaluation IDs include:

ModelIDNotes
Gemma 4 31B ITgemma-4-31b-itLarger Gemma model; useful for compatibility and quality evaluation
Gemma 4 26B A4B ITgemma-4-26b-a4b-itSmaller active-parameter variant when available

These models are best treated as evaluation options on Gemini API keys. Google's Gemma API pricing is free-tier-only and the usage caps are low compared with production Gemini models, so sustained Nedura agent use should normally move to a paid Gemini model, a self-hosted deployment, or another provider with appropriate quota.

To use a Gemma model that is hidden from the picker, set it directly:

model:
  default: gemma-4-31b-it
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta

Switching Models Mid-Session​

Use the /model command during a conversation:

/model gemini-3.7-flash
/model gemini-flash-latest
/model gemini-3.1-pro-preview
/model gemini-pro-latest
/model gemma-4-31b-it
/model gemini-3.1-flash-lite-preview

If you have not configured Gemini yet, exit the session and run nedura model first. /model switches among already-configured providers and models; it does not collect new API keys.

Diagnostics​

nedura doctor

The doctor checks:

  • Whether GOOGLE_API_KEY or GEMINI_API_KEY is available
  • Whether configured provider credentials can be resolved

Gateway (Messaging Platforms)​

Gemini works with all Nedura gateway platforms (Telegram, Discord, Slack, WhatsApp, LINE, Feishu, etc.). Configure Gemini as your provider, then start the gateway normally:

nedura gateway setup
nedura gateway start

The gateway reads config.yaml and uses the same Gemini provider configuration.

Troubleshooting​

"Gemini native client requires an API key"​

Nedura could not find a usable API key. Add one of these to ~/.nedura/.env:

GOOGLE_API_KEY=...
# or
GEMINI_API_KEY=...

Then run nedura model again.

"This Google API key is on the free tier"​

Nedura probes Gemini API keys during setup. Free-tier quotas can be exhausted after a handful of agent turns because tool use, retries, compression, and auxiliary tasks may require multiple model calls.

Enable billing on the Google Cloud project attached to your key, regenerate the key if needed, then run:

nedura model

"404 model not found"​

The selected model is not available for your account, region, or key. Run nedura model again and pick another Gemini model from the current list.

Gemma model is not shown in nedura model​

Nedura may hide low-throughput Gemma models from the picker by default. If you intentionally want to evaluate one, set the model ID directly in ~/.nedura/config.yaml.

"429 quota exceeded" on Gemma​

Gemma models exposed through the Gemini API are useful for evaluation, but their Gemini API free-tier caps are low. Use them for compatibility testing, then switch to a paid Gemini model or another provider for sustained agent sessions.

OpenAI-compatible endpoint is configured​

Check ~/.nedura/.env for:

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/

Change it to the native endpoint or remove the override:

GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta

Tool calling fails with schema errors​

Upgrade Nedura and rerun nedura model. The native Gemini adapter sanitizes tool schemas for Gemini's stricter function-declaration format; older builds or custom endpoints may not.