> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mibyanai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Gemini

> Use Mibyan with Google Gemini — native AI Studio API, API-key setup, tool calling, streaming, and quota guidance

Mibyan supports Google Gemini as a native provider using the **Google AI Studio / Gemini API** — not the OpenAI-compatible endpoint. This lets Mibyan 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](https://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 Mibyan may make several model calls per user turn.
* **Mibyan installed** — no extra Python package is required for the native Gemini provider.

<Tip>
  **API key path**

  Set `GOOGLE_API_KEY` or `GEMINI_API_KEY`. Mibyan checks both names for the `gemini` provider.
</Tip>

## Quick Start

```bash theme={null}
# Add your Gemini API key
echo "GOOGLE_API_KEY=..." >> ~/.mibyan/.env

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

# Start chatting
mibyan chat
```

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

```yaml theme={null}
model:
  default: gemini-3.7-flash
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta
```

## Configuration

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

```yaml theme={null}
model:
  default: gemini-3.7-flash
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta
```

And in `~/.mibyan/.env`:

```bash theme={null}
GOOGLE_API_KEY=...
```

### Native Gemini API

The recommended endpoint is:

```text theme={null}
https://generativelanguage.googleapis.com/v1beta
```

Mibyan detects this endpoint and creates its native Gemini adapter. Internally, Mibyan 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 Mibyan 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.

<Note>
  **Gemini 3 thought signatures**

  For Gemini 3 tool use, Mibyan 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. Mibyan' 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.
</Note>

### Prefer the Native Endpoint

Google also exposes an OpenAI-compatible endpoint:

```text theme={null}
https://generativelanguage.googleapis.com/v1beta/openai/
```

For Mibyan agent sessions, prefer the native Gemini endpoint above. Mibyan 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:

```bash theme={null}
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`, ...), Mibyan
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. Mibyan 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 Mibyan 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 Mibyan 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](/desktop/guides/google-vertex), which needs no API key.

<Warning>
  **Upgrade note for existing express-key users**

  Earlier Mibyan 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,
  `mibyan 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 `~/.mibyan/.env` (or set `base_url` on the provider) once and restart.
</Warning>

## Available Models

The `mibyan model` picker shows Gemini models maintained in Mibyan' provider registry. Common choices include:

| Model | ID | Notes |
| - | - | - |
| Gemini 3.8 Flash | `gemini-3.8-flash` | Most capable Flash model for long-horizon agentic and coding work |
| Gemini 3.7 Flash | `gemini-3.7-flash` | Recommended default balance of speed, capability, and multimodal understanding |
| Gemini 3.1 Pro Preview | `gemini-3.1-pro-preview` | Most capable reasoning, math, and coding model |
| Gemini 3.5 Flash Lite | `gemini-3.5-flash-lite` | Fastest and lowest-cost option for lightweight tasks |
| Gemini 2.5 Flash | `gemini-2.5-flash` | Previous generation fast model with thinking capabilities |
| Gemini 2.5 Pro | `gemini-2.5-pro` | Previous generation complex reasoning model |

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

<Info>
  **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`.
</Info>

### 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 Mibyan config. Note that your usage charges may be affected if newer models introduce different rates.

| Alias | Currently tracks | Notes |
| - | - | - |
| `gemini-pro-latest` | Latest Gemini Pro model | Best when you want Google's current Pro default |
| `gemini-flash-latest` | Latest Gemini Flash model | Best when you want Google's current Flash default |

```yaml theme={null}
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. Mibyan 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:

| Model | ID | Notes |
| - | - | - |
| Gemma 4 31B IT | `gemma-4-31b-it` | Larger Gemma model; useful for compatibility and quality evaluation |
| Gemma 4 26B A4B IT | `gemma-4-26b-a4b-it` | Smaller 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 Mibyan 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:

```yaml theme={null}
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:

```text theme={null}
/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 `mibyan model` first. `/model` switches among already-configured providers and models; it does not collect new API keys.

## Diagnostics

```bash theme={null}
mibyan 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 Mibyan gateway platforms (Telegram, Discord, Slack, WhatsApp, LINE, Feishu, etc.). Configure Gemini as your provider, then start the gateway normally:

```bash theme={null}
mibyan gateway setup
mibyan gateway start
```

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

## Troubleshooting

### "Gemini native client requires an API key"

Mibyan could not find a usable API key. Add one of these to `~/.mibyan/.env`:

```bash theme={null}
GOOGLE_API_KEY=...
# or
GEMINI_API_KEY=...
```

Then run `mibyan model` again.

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

Mibyan 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:

```bash theme={null}
mibyan model
```

### "404 model not found"

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

### Gemma model is not shown in `mibyan model`

Mibyan may hide low-throughput Gemma models from the picker by default. If you intentionally want to evaluate one, set the model ID directly in `~/.mibyan/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 `~/.mibyan/.env` for:

```bash theme={null}
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
```

Change it to the native endpoint or remove the override:

```bash theme={null}
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
```

### Tool calling fails with schema errors

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

## Related

* [AI Providers](/desktop/integrations/providers)
* [Configuration](/desktop/user-guide/configuration)
* [Fallback Providers](/desktop/user-guide/features/fallback-providers)
* [AWS Bedrock](/desktop/guides/aws-bedrock) — native cloud-provider integration using AWS credentials


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.