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

# Google Gemini Drop-in

> Route Google Gemini requests through MetrixLLM with a one-line base URL change.

## Base URL

```text theme={null}
https://gateway.metrixllm.com/gemini
```

## Quick setup

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://gateway.metrixllm.com/gemini/v1beta/models/gemini-2.0-flash:generateContent"
  headers = {
      "Content-Type": "application/json",
      "x-api-key": "sk-metrix-YOUR_API_KEY"
  }
  payload = {
      "contents": [
          {"role": "user", "parts": [{"text": "Hello!"}]}
      ]
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json()["candidates"][0]["content"]["parts"][0]["text"])
  ```

  ```typescript Node.js theme={null}
  const response = await fetch(
      "https://gateway.metrixllm.com/gemini/v1beta/models/gemini-2.0-flash:generateContent",
      {
          method: "POST",
          headers: {
              "Content-Type": "application/json",
              "x-api-key": "sk-metrix-YOUR_API_KEY"
          },
          body: JSON.stringify({
              contents: [
                  { role: "user", parts: [{ text: "Hello!" }] }
              ]
          })
      }
  );
  const data = await response.json();
  console.log(data.candidates[0].content.parts[0].text);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://gateway.metrixllm.com/gemini/v1beta/models/gemini-2.0-flash:generateContent" \
    -H "Content-Type: application/json" \
    -H "x-api-key: sk-metrix-YOUR_API_KEY" \
    -d '{
      "contents": [
        {"role": "user", "parts": [{"text": "Hello!"}]}
      ]
    }'
  ```
</CodeGroup>

<Warning>
  Do **not** use your Google API key. The gateway authenticates with MetrixLLM keys (`sk-metrix-*` prefix), then uses its own provider keys (or your BYOK keys) to call Google.
</Warning>

## Request Headers

Every request supports these headers for authentication, tracing, and metadata:

| Header          | Type     | Required | Description                                           |
| --------------- | -------- | -------- | ----------------------------------------------------- |
| `x-api-key`     | `string` | Yes\*    | `sk-metrix-{key}` — MetrixLLM API key                 |
| `Authorization` | `string` | Yes\*    | `Bearer sk-metrix-{key}` — alternative to `x-api-key` |
| `Content-Type`  | `string` | Yes      | Must be `application/json`                            |

**Session Tracing**

| Header                | Description                                                                  | Stored In                   |
| --------------------- | ---------------------------------------------------------------------------- | --------------------------- |
| `metrix-session-id`   | Unique session identifier — groups related requests into a traceable session | `workspace_logs.session_id` |
| `metrix-parent-id`    | Links a request to a parent span in the session trace                        | `workspace_logs.parent_id`  |
| `metrix-session-name` | Human-readable name for the span (for dashboard display)                     | `workspace_logs.span_name`  |

**Custom Properties**

Attach up to 10 custom metadata properties per request:

| Header Pattern          | Description                                                                        |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `metrix-property-{key}` | Custom metadata property. Used for rate limit targeting, analytics, and filtering. |

Example: `metrix-property-team: engineering`, `metrix-property-environment: production`

**IP Detection**

| Header            | Description                                          |
| ----------------- | ---------------------------------------------------- |
| `x-forwarded-for` | Client IP address (first IP in comma-separated list) |
| `x-real-ip`       | Fallback client IP header                            |
| `cf-ipcountry`    | Cloudflare country code of the connecting client     |

## Supported models

| Model            | ID                 |
| ---------------- | ------------------ |
| Gemini 2.0 Flash | `gemini-2.0-flash` |

## Routing mode

Control how the gateway authenticates with Google Gemini using the `mode` parameter:

| Mode               | Behavior                                                               | Balance deduction                     |
| ------------------ | ---------------------------------------------------------------------- | ------------------------------------- |
| `"auto"` (default) | Uses your BYOK key if configured, otherwise falls back to platform key | BYOK: none. Native: yes               |
| `"byok"`           | Forces your own Google API key (from workspace settings)               | None — your key, your cost            |
| `"native"`         | Forces MetrixLLM's platform key                                        | Yes — deducted from workspace credits |

<CodeGroup>
  ```python Python theme={null}
  # Use your own Google key (BYOK) — never deducts workspace credits
  payload = {
      "contents": [
          {"role": "user", "parts": [{"text": "Hello!"}]}
      ],
      "mode": "byok"
  }
  response = requests.post(url, json=payload, headers=headers)
  ```

  ```typescript Node.js theme={null}
  const response = await fetch(
      "https://gateway.metrixllm.com/gemini/v1beta/models/gemini-2.0-flash:generateContent",
      {
          method: "POST",
          headers: {
              "Content-Type": "application/json",
              "x-api-key": "sk-metrix-YOUR_API_KEY"
          },
          body: JSON.stringify({
              contents: [
                  { role: "user", parts: [{ text: "Hello!" }] }
              ],
              mode: "byok"
          })
      }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST "https://gateway.metrixllm.com/gemini/v1beta/models/gemini-2.0-flash:generateContent" \
    -H "Content-Type: application/json" \
    -H "x-api-key: sk-metrix-YOUR_API_KEY" \
    -d '{
      "contents": [
        {"role": "user", "parts": [{"text": "Hello!"}]}
      ],
      "mode": "byok"
    }'
  ```
</CodeGroup>

<Note>
  When `mode` is omitted (or `"auto"`), the gateway prefers your BYOK key if one is configured. If your workspace has insufficient credits and you have a BYOK key, the gateway automatically uses it instead of failing with a payment error.
</Note>

## Web search

### Web search mode (default)

Add `"web_search": true` to your request. The gateway performs a web search, generates optimized search queries, and injects the results into your system prompt.

<CodeGroup>
  ```python Python theme={null}
  payload = {
      "contents": [
          {"role": "user", "parts": [{"text": "What happened in the news today?"}]}
      ],
      "web_search": True
  }
  response = requests.post(url, json=payload, headers=headers)
  ```

  ```typescript Node.js theme={null}
  const response = await fetch(
      "https://gateway.metrixllm.com/gemini/v1beta/models/gemini-2.0-flash:generateContent",
      {
          method: "POST",
          headers: {
              "Content-Type": "application/json",
              "x-api-key": "sk-metrix-YOUR_API_KEY"
          },
          body: JSON.stringify({
              contents: [
                  { role: "user", parts: [{ text: "What happened in the news today?" }] }
              ],
              web_search: true
          })
      }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST "https://gateway.metrixllm.com/gemini/v1beta/models/gemini-2.0-flash:generateContent" \
    -H "Content-Type: application/json" \
    -H "x-api-key: sk-metrix-YOUR_API_KEY" \
    -d '{
      "contents": [
        {"role": "user", "parts": [{"text": "What happened in the news today?"}]}
      ],
      "web_search": true
    }'
  ```
</CodeGroup>

**Parameters:**

| Parameter            | Type      | Default    | Description                                                                                      |
| -------------------- | --------- | ---------- | ------------------------------------------------------------------------------------------------ |
| `web_search`         | `boolean` | `false`    | Set to `true` to enable web search                                                               |
| `web_search_level`   | `string`  | `"medium"` | `"low"` (1 query, 3 results), `"medium"` (2 queries, 5 results), `"high"` (3 queries, 8 results) |
| `web_search_lang`    | `string`  | `"en"`     | Search language (ISO code)                                                                       |
| `web_search_country` | `string`  | `"us"`     | Search country (ISO code)                                                                        |

### Native mode

Set `"web_search": "native"` to use Google's built-in web search. The gateway adds the `google_search` tool to your request.

<CodeGroup>
  ```python Python theme={null}
  payload = {
      "contents": [
          {"role": "user", "parts": [{"text": "What's the latest AI news?"}]}
      ],
      "tools": [
          {"google_search": {}}
      ]
  }
  response = requests.post(url, json=payload, headers=headers)
  ```

  ```typescript Node.js theme={null}
  const response = await fetch(
      "https://gateway.metrixllm.com/gemini/v1beta/models/gemini-2.0-flash:generateContent",
      {
          method: "POST",
          headers: {
              "Content-Type": "application/json",
              "x-api-key": "sk-metrix-YOUR_API_KEY"
          },
          body: JSON.stringify({
              contents: [
                  { role: "user", parts: [{ text: "What's the latest AI news?" }] }
              ],
              tools: [{ google_search: {} }]
          })
      }
  );
  ```

  ```bash cURL theme={null}
  curl -X POST "https://gateway.metrixllm.com/gemini/v1beta/models/gemini-2.0-flash:generateContent" \
    -H "Content-Type: application/json" \
    -H "x-api-key: sk-metrix-YOUR_API_KEY" \
    -d '{
      "contents": [
        {"role": "user", "parts": [{"text": "What'\''s the latest AI news?"}]}
      ],
      "tools": [
        {"google_search": {}}
      ]
    }'
  ```
</CodeGroup>

<Note>
  In native mode, the gateway detects `google_search` or `googleSearch` tools in your request and automatically sets `web_search: "native"` internally. You can also pass `"web_search": "native"` in the request body and the gateway will add the tool for you.
</Note>

## Generation configuration

Control output generation with standard Gemini parameters:

```python theme={null}
payload = {
    "contents": [
        {"role": "user", "parts": [{"text": "Write a poem"}]}
    ],
    "generationConfig": {
        "temperature": 0.7,
        "topP": 0.9,
        "topK": 40,
        "maxOutputTokens": 1024
    }
}
```

| Parameter         | Type      | Description                |
| ----------------- | --------- | -------------------------- |
| `temperature`     | `number`  | Sampling temperature (0-2) |
| `topP`            | `number`  | Nucleus sampling parameter |
| `topK`            | `number`  | Top-K sampling parameter   |
| `maxOutputTokens` | `integer` | Maximum output tokens      |

## Extended thinking

Gemini supports extended thinking for complex reasoning:

```python theme={null}
payload = {
    "contents": [
        {"role": "user", "parts": [{"text": "Solve this step by step: what is 2^10 + 3^5?"}]}
    ],
    "generationConfig": {
        "thinkingConfig": {
            "thinkingBudget": 10000
        }
    }
}
```

## Tool use (function calling)

```python theme={null}
payload = {
    "contents": [
        {"role": "user", "parts": [{"text": "What's the weather in London?"}]}
    ],
    "tools": [
        {
            "functionDeclarations": [
                {
                    "name": "get_weather",
                    "description": "Get current weather for a location",
                    "parameters": {
                        "type": "OBJECT",
                        "properties": {
                            "location": {"type": "STRING", "description": "City name"}
                        },
                        "required": ["location"]
                    }
                }
            ]
        }
    ]
}
```

## Streaming

```python theme={null}
payload = {
    "contents": [
        {"role": "user", "parts": [{"text": "Tell me a story"}]}
    ]
}

response = requests.post(
    url + "?alt=sse",
    json=payload,
    headers=headers,
    stream=True
)
for line in response.iter_lines():
    if line:
        print(line.decode())
```

## Prompt management

Reference a stored prompt template by ID:

```python theme={null}
payload = {
    "contents": [
        {"role": "user", "parts": [{"text": "Hello!"}]}
    ],
    "prompt_id": "your-prompt-uuid",
    "inputs": {"user_name": "Alice"}
}
```

## Custom properties

Attach metadata via HTTP headers:

```python theme={null}
headers = {
    "Content-Type": "application/json",
    "x-api-key": "sk-metrix-YOUR_API_KEY",
    "metrix-property-team": "backend",
    "metrix-property-env": "production",
    "metrix-session-id": "session_abc123"
}
```

## Response headers

Every response includes these headers:

| Header                           | Description                                                             |
| -------------------------------- | ----------------------------------------------------------------------- |
| `Content-Type`                   | Always `application/json`                                               |
| `X-Metrix-Provider`              | Provider that served the request (e.g. `google`, `openai`, `anthropic`) |
| `X-Metrix-Model`                 | Exact model used for the request                                        |
| `X-Metrix-Cache-Status`          | `"HIT"` or `"miss"` (semantic cache)                                    |
| `X-Metrix-Retry-Count`           | Number of retry attempts (0 if none)                                    |
| `X-Metrix-Retry-Status`          | `"success"`, `"failed"`, or `"not_triggered"`                           |
| `X-Metrix-Fallback`              | `"true"` if a fallback provider was used (only when applicable)         |
| `X-RateLimit-Limit`              | Configured limit for the rate window                                    |
| `X-RateLimit-Remaining`          | Remaining quota in the current window                                   |
| `X-RateLimit-Requests-Remaining` | Remaining requests in current window                                    |
| `X-RateLimit-Tokens-Remaining`   | Remaining tokens in current window                                      |

On cache HIT responses, only `Content-Type` and `X-Metrix-Cache-Status: HIT` are returned.

On rate limited responses (`429 Too Many Requests`):

| Header                         | Description                                                           |
| ------------------------------ | --------------------------------------------------------------------- |
| `Retry-After`                  | Seconds to wait before retrying                                       |
| `X-RateLimit-{type}-Limit`     | Maximum limit (e.g. `X-RateLimit-rpm-Limit`, `X-RateLimit-tpm-Limit`) |
| `X-RateLimit-{type}-Remaining` | Remaining count in the current window                                 |
| `X-RateLimit-Reset`            | Seconds until the rate window resets                                  |