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

# Google Gen AI SDK

> Connect Google's Gen AI SDK to the ngrok AI Gateway with Python and TypeScript examples for GenerateContent, streaming, and stateless Interactions.

> [!NOTE]
>
> **Prerequisite**: Complete the [quickstart](https://ngrok.com/docs/ai-gateway/quickstart.md) to create an [access key](https://ngrok.com/docs/ai-gateway/concepts/access-keys.md).
> See [Google provider setup](https://ngrok.com/docs/ai-gateway/providers/google.md#setup) to configure Google routing or bring your own Google key.

Use Google's Gen AI SDK for [Python](https://googleapis.github.io/python-genai/) or [TypeScript](https://googleapis.github.io/js-genai/) with the AI Gateway.
Set the base URL to `https://gateway.ngrok.ai`, use API version `v1beta`, and authenticate with your ngrok access key.

> [!NOTE]
>
> Google models also work through OpenAI-compatible Chat Completions.
> See the [OpenAI SDK guide](https://ngrok.com/docs/ai-gateway/sdks/openai.md) to use your existing OpenAI client with a Google model name.
> The OpenAI Responses API (`/v1/responses`) doesn't reach Google models.

## Installation

```bash Python theme={"theme":{"light":"css-variables","dark":"css-variables"}}
pip install --upgrade google-genai
```

```bash TypeScript theme={"theme":{"light":"css-variables","dark":"css-variables"}}
npm install @google/genai
```

## Basic usage

Set `NGROK_AI_GATEWAY_KEY` to your ngrok access key, then send a GenerateContent request:

```python Python highlight={7-11} theme={"theme":{"light":"css-variables","dark":"css-variables"}}
import os

from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["NGROK_AI_GATEWAY_KEY"],
    http_options=types.HttpOptions(
        base_url="https://gateway.ngrok.ai",
        api_version="v1beta",
    ),
)

response = client.models.generate_content(
    model="gemini-3.6-flash",
    contents="Hello",
)

print(response.text)
```

```typescript TypeScript highlight={4-8} theme={"theme":{"light":"css-variables","dark":"css-variables"}}
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
  apiKey: process.env.NGROK_AI_GATEWAY_KEY,
  httpOptions: {
    baseUrl: "https://gateway.ngrok.ai",
    apiVersion: "v1beta",
  },
});

const response = await client.models.generateContent({
  model: "gemini-3.6-flash",
  contents: "Hello",
});

console.log(response.text);
```

## Streaming

Use the SDK's streaming method to print text as it arrives:

```python Python highlight={14-19} theme={"theme":{"light":"css-variables","dark":"css-variables"}}
import os

from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["NGROK_AI_GATEWAY_KEY"],
    http_options=types.HttpOptions(
        base_url="https://gateway.ngrok.ai",
        api_version="v1beta",
    ),
)

for chunk in client.models.generate_content_stream(
    model="gemini-3.6-flash",
    contents="Write a haiku about APIs",
):
    if chunk.text:
        print(chunk.text, end="", flush=True)
```

```typescript TypeScript highlight={11-18} theme={"theme":{"light":"css-variables","dark":"css-variables"}}
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
  apiKey: process.env.NGROK_AI_GATEWAY_KEY,
  httpOptions: {
    baseUrl: "https://gateway.ngrok.ai",
    apiVersion: "v1beta",
  },
});

const stream = await client.models.generateContentStream({
  model: "gemini-3.6-flash",
  contents: "Write a haiku about APIs",
});

for await (const chunk of stream) {
  process.stdout.write(chunk.text ?? "");
}
```

## Interactions

Send `model` and `input` to create a stateless interaction.
Set `store=false` explicitly:

```python Python highlight={14-18} theme={"theme":{"light":"css-variables","dark":"css-variables"}}
import os

from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["NGROK_AI_GATEWAY_KEY"],
    http_options=types.HttpOptions(
        base_url="https://gateway.ngrok.ai",
        api_version="v1beta",
    ),
)

response = client.interactions.create(
    model="gemini-3.6-flash",
    input="Hello",
    store=False,
)

print(response.output_text)
```

```typescript TypeScript highlight={11-15} theme={"theme":{"light":"css-variables","dark":"css-variables"}}
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({
  apiKey: process.env.NGROK_AI_GATEWAY_KEY,
  httpOptions: {
    baseUrl: "https://gateway.ngrok.ai",
    apiVersion: "v1beta",
  },
});

const response = await client.interactions.create({
  model: "gemini-3.6-flash",
  input: "Hello",
  store: false,
});

console.log(response.output_text);
```

Interactions through the gateway are stateless.
The gateway rejects `store=true` and sends every valid request to Google with `store=false`, even if you omit `store` or set it to `null`.

Requests paid with credits and bring your own key (BYOK) requests both have these restrictions:

* Stored conversation chaining (`previous_interaction_id`) and background execution (`background=true`) are unsupported.
* Interaction retrieval, deletion, cancellation, and stream resumption are unsupported.
* Agents, environments, webhooks, and triggers are unsupported.

> [!NOTE]
>
> Interactions requests paid with credits support text input and text or structured JSON output only.
> Use the Standard tier: omit `service_tier` or set it to `standard`.
> The `gemini-3.1-pro-preview` and `gemini-3.1-pro-preview-customtools` models require BYOK for Interactions because they use context-band pricing.
> With BYOK, supported input and output formats and service tiers depend on Google and the selected model.

## Authentication

Use your ngrok access key to authenticate requests to the gateway.
The gateway checks credentials in this order:

1. `Authorization: Bearer <NGROK_AI_GATEWAY_KEY>`
2. `X-Api-Key: <NGROK_AI_GATEWAY_KEY>`
3. `X-Goog-Api-Key: <NGROK_AI_GATEWAY_KEY>`, which the Google SDK sets from `api_key` in Python or `apiKey` in TypeScript.

The URL query parameter `key` fills an empty `X-Goog-Api-Key` header.
It doesn't override a header credential.
Prefer headers to keep credentials out of URLs.

Your access key identifies your gateway configuration.
A Google provider key is a separate credential stored in the gateway.
For BYOK, attach the stored Google key to your configuration; continue to send your ngrok access key from the client.
The gateway replaces client credentials with the selected Google provider credential before forwarding the request.

## Supported endpoints

The gateway supports these native Gemini endpoints:

| Endpoint | Description |
| - | - |
| `/v1beta/models/{model}:generateContent` | GenerateContent with a JSON response |
| `/v1beta/models/{model}:streamGenerateContent?alt=sse` | Streaming GenerateContent |
| `/v1beta/interactions` | Stateless Interactions with a JSON or streaming response |

### Generate content requests

Point a Gemini client at `https://gateway.ngrok.ai` and send your access key as described in [Authentication](#authentication).
Use `POST /v1beta/models/{model}:generateContent` for a JSON response.
For streaming, use `POST /v1beta/models/{model}:streamGenerateContent?alt=sse`.
The `alt=sse` query parameter is required.

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl "https://gateway.ngrok.ai/v1beta/models/gemini-3.6-flash:generateContent" \
  -H "X-Goog-Api-Key: ng-xxxxx-g1-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Hello"}]}]}'
```

Use Google's native GenerateContent payload format.
The gateway filters request parameters for the selected backend and applies output-token limits.

Responses include the gateway response headers: `Ngrok-AIG-Request-Id` on every response, `Ngrok-AIG-Attempts` once the upstream attempt loop runs, and `Ngrok-AIG-Model` on success.
See [Response headers](https://ngrok.com/docs/ai-gateway/how-it-works.md#response-headers).

### Interactions requests

Send `POST /v1beta/interactions` with `model` and `input` in the request body.
The REST base URL is `https://gateway.ngrok.ai/v1beta/`.
Omit `stream` or set it to `false` for a JSON response.
Set `stream=true` for server-sent events (SSE).

Responses use Google's native Interactions format and include the [gateway response headers](https://ngrok.com/docs/ai-gateway/how-it-works.md#response-headers).

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl -X POST \
  "https://gateway.ngrok.ai/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "X-Goog-Api-Key: ng-xxxxx-g1-xxxxx" \
  -d '{
    "model": "gemini-3.6-flash",
    "input": "Hello!",
    "store": false
  }'
```

## Next steps

* [Configure Google as a provider](https://ngrok.com/docs/ai-gateway/providers/google.md)
* [Browse Google models](https://ngrok.com/docs/ai-gateway/reference/model-catalog.md#google)
* [Configure access keys](https://ngrok.com/docs/ai-gateway/guides/access-key-configurations.md)


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