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

# Compat introduction

# Gemini Compat API

The **Gemini Compat API** is a **drop-in replacement** for Google's official Gemini API. It's fully compatible with Google's official **@google/genai** SDK and the Gemini REST interface — just change the base URL and API key, and everything works out of the box.

<Tip>
  **No code changes needed** — if you already use `@google/genai` or call Gemini's REST API, simply point your SDK to `https://api.mountsea.ai/gemini` with your Mountsea API key.
</Tip>

## Why Use Compat API?

<CardGroup cols={2}>
  <Card title="Official SDK Support" icon="code">
    Works with Google's official `@google/genai` (TypeScript) and `google-genai` (Python) libraries
  </Card>

  <Card title="Same API Shape" icon="equals">
    Uses the same `generateContent` / `streamGenerateContent` endpoints and request/response schema
  </Card>

  <Card title="Unified Billing" icon="wallet">
    Single API key, unified usage tracking and billing through Mountsea
  </Card>

  <Card title="Image Generation" icon="image">
    Supports image generation via `gemini-*-image` models (auto-routed to Nano Banana)
  </Card>
</CardGroup>

## Configuration

### Base URL

```
https://api.mountsea.ai/gemini
```

### Authentication

Use your **Mountsea API key** (Bearer token). It can be passed as either:

* HTTP header: `Authorization: Bearer your-api-key`
* Or via the official SDK's `apiKey` parameter

## Image Model Mapping

When calling Compat API with an image model name, it's automatically routed to the corresponding Nano Banana model:

| Gemini Model ID (input)          | Routed to (Nano Banana) |
| -------------------------------- | ----------------------- |
| `gemini-2.5-flash-image`         | `NanoBananaFast`        |
| `gemini-3.1-flash-image-preview` | `NanoBanana2`           |
| `gemini-3-pro-image-preview`     | `NanoBananaPro`         |

<Info>
  You can use **either** the Gemini model IDs above **or** the native Nano Banana model IDs (`nano-banana-fast`, `nano-banana-2`, `nano-banana-pro`) — both work.
</Info>

***

## Using the Official @google/genai SDK

### Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @google/genai
  ```

  ```bash pnpm theme={null}
  pnpm add @google/genai
  ```

  ```bash yarn theme={null}
  yarn add @google/genai
  ```

  ```bash pip theme={null}
  pip install google-genai
  ```
</CodeGroup>

### TypeScript / JavaScript

<CodeGroup>
  ```typescript Text Generation theme={null}
  import { GoogleGenAI } from '@google/genai';

  const ai = new GoogleGenAI({
    apiKey: 'your-mountsea-api-key',
    httpOptions: {
      baseUrl: 'https://api.mountsea.ai/gemini',
    },
  });

  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'Explain quantum computing in one paragraph',
  });

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

  ```typescript Streaming theme={null}
  import { GoogleGenAI } from '@google/genai';

  const ai = new GoogleGenAI({
    apiKey: 'your-mountsea-api-key',
    httpOptions: {
      baseUrl: 'https://api.mountsea.ai/gemini',
    },
  });

  const stream = await ai.models.generateContentStream({
    model: 'gemini-2.5-flash',
    contents: 'Write a short poem about the sea',
  });

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

  ```typescript Image Generation theme={null}
  import { GoogleGenAI } from '@google/genai';
  import fs from 'fs';

  const ai = new GoogleGenAI({
    apiKey: 'your-mountsea-api-key',
    httpOptions: {
      baseUrl: 'https://api.mountsea.ai/gemini',
    },
  });

  const response = await ai.models.generateContent({
    model: 'gemini-3-pro-image-preview', // → NanoBananaPro
    contents: 'A futuristic city skyline at night, neon reflections on wet streets',
    config: {
      responseModalities: ['image', 'text'],
      imageConfig: {
        aspectRatio: '16:9',
        imageSize: '2K',
      },
    },
  });

  for (const part of response.candidates?.[0]?.content?.parts ?? []) {
    if (part.inlineData?.data) {
      fs.writeFileSync('output.png', Buffer.from(part.inlineData.data, 'base64'));
    } else if (part.text) {
      console.log(part.text);
    }
  }
  ```

  ```typescript Image Editing theme={null}
  import { GoogleGenAI } from '@google/genai';
  import fs from 'fs';

  const ai = new GoogleGenAI({
    apiKey: 'your-mountsea-api-key',
    httpOptions: {
      baseUrl: 'https://api.mountsea.ai/gemini',
    },
  });

  const sourceImage = fs.readFileSync('source.jpg').toString('base64');

  const response = await ai.models.generateContent({
    model: 'gemini-2.5-flash-image', // → NanoBananaFast
    contents: [
      {
        role: 'user',
        parts: [
          { text: 'Add snow falling throughout the scene' },
          {
            inlineData: {
              mimeType: 'image/jpeg',
              data: sourceImage,
            },
          },
        ],
      },
    ],
    config: {
      responseModalities: ['image'],
      imageConfig: { aspectRatio: '1:1' },
    },
  });

  const imgPart = response.candidates?.[0]?.content?.parts?.find((p) => p.inlineData);
  if (imgPart?.inlineData?.data) {
    fs.writeFileSync('edited.png', Buffer.from(imgPart.inlineData.data, 'base64'));
  }
  ```
</CodeGroup>

### Python

<CodeGroup>
  ```python Text Generation theme={null}
  from google import genai
  from google.genai import types

  client = genai.Client(
      api_key="your-mountsea-api-key",
      http_options=types.HttpOptions(base_url="https://api.mountsea.ai/gemini"),
  )

  response = client.models.generate_content(
      model="gemini-2.5-flash",
      contents="Explain quantum computing in one paragraph",
  )
  print(response.text)
  ```

  ```python Streaming theme={null}
  from google import genai
  from google.genai import types

  client = genai.Client(
      api_key="your-mountsea-api-key",
      http_options=types.HttpOptions(base_url="https://api.mountsea.ai/gemini"),
  )

  stream = client.models.generate_content_stream(
      model="gemini-2.5-flash",
      contents="Write a short poem about the sea",
  )

  for chunk in stream:
      print(chunk.text, end="", flush=True)
  ```

  ```python Image Generation theme={null}
  from google import genai
  from google.genai import types

  client = genai.Client(
      api_key="your-mountsea-api-key",
      http_options=types.HttpOptions(base_url="https://api.mountsea.ai/gemini"),
  )

  response = client.models.generate_content(
      model="gemini-3-pro-image-preview",  # → NanoBananaPro
      contents="A futuristic city skyline at night",
      config=types.GenerateContentConfig(
          response_modalities=["image", "text"],
          image_config=types.ImageConfig(aspect_ratio="16:9", image_size="2K"),
      ),
  )

  for part in response.candidates[0].content.parts:
      if part.inline_data:
          with open("output.png", "wb") as f:
              f.write(part.inline_data.data)
      elif part.text:
          print(part.text)
  ```
</CodeGroup>

***

## Using the Gemini REST API

If you don't want to use the SDK, you can call the endpoint directly. It's identical in shape to Google's official REST API.

### Endpoint

```
POST https://api.mountsea.ai/gemini/v1beta/models/{model}:{action}
```

Where:

* `{model}` — model ID (e.g. `gemini-2.5-flash`, `gemini-3-pro-image-preview`)
* `{action}` — `generateContent` (JSON response) or `streamGenerateContent` (SSE stream)

### Text Generation

```bash theme={null}
curl -X POST "https://api.mountsea.ai/gemini/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "Explain quantum computing in one paragraph" }]
      }
    ]
  }'
```

### Image Generation

```bash theme={null}
curl -X POST "https://api.mountsea.ai/gemini/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{ "text": "A futuristic city skyline at night" }]
      }
    ],
    "generationConfig": {
      "responseModalities": ["image", "text"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }'
```

### Image Editing

Include an image as `inline_data` in the `parts` array:

```bash theme={null}
curl -X POST "https://api.mountsea.ai/gemini/v1beta/models/gemini-2.5-flash-image:generateContent" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Add snow falling throughout the scene" },
          {
            "inline_data": {
              "mime_type": "image/jpeg",
              "data": "<base64-encoded-image-bytes>"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["image"],
      "imageConfig": { "aspectRatio": "1:1" }
    }
  }'
```

### Streaming

Change `generateContent` to `streamGenerateContent` to receive a Server-Sent Events (SSE) stream:

```bash theme={null}
curl -X POST "https://api.mountsea.ai/gemini/v1beta/models/gemini-2.5-flash:streamGenerateContent" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "role": "user", "parts": [{ "text": "Write a short poem" }] }
    ]
  }'
```

***

## Image Generation Config

When requesting image generation (`response_modalities` includes `image`), you can configure the output:

| Field                          | Location                       | Description  | Example                     |
| ------------------------------ | ------------------------------ | ------------ | --------------------------- |
| `aspectRatio` / `aspect_ratio` | `generationConfig.imageConfig` | Aspect ratio | `"1:1"`, `"16:9"`, `"9:16"` |
| `imageSize` / `image_size`     | `generationConfig.imageConfig` | Resolution   | `"1K"`, `"2K"`, `"4K"`      |

<Info>
  Both camelCase (`aspectRatio`, `imageSize`) and snake\_case (`aspect_ratio`, `image_size`) are accepted. These fields can also be placed directly on `generationConfig` as shortcuts.
</Info>

### Supported Aspect Ratios (by Model)

* **`gemini-2.5-flash-image`** (→ NanoBananaFast): `1:1`, `4:3`, `3:2`, `2:3`, `5:4`, `4:5`, `3:4`, `16:9`, `9:16`, `21:9`
* **`gemini-3-pro-image-preview`** (→ NanoBananaPro): all standard ratios
* **`gemini-3.1-flash-image-preview`** (→ NanoBanana2): all standard ratios + `1:4`, `4:1`, `1:8`, `8:1`

***

## Notes & Limitations

<Warning>
  Currently the Compat endpoint returns **1 image per request**. The `candidateCount` field is accepted for compatibility but has no effect — it's treated as 1.
</Warning>

* For image generation, always include `responseModalities: ["image"]` (or `["image", "text"]`) in `generationConfig`.
* The `inline_data.data` field should be raw base64 (no `data:*;base64,` prefix).
* Both `inline_data` (snake\_case) and `inlineData` (camelCase) are accepted.

***

## Available Endpoint

| Endpoint                              | Method | Description                                               |
| ------------------------------------- | ------ | --------------------------------------------------------- |
| `/gemini/v1beta/models/{modelAction}` | POST   | Gemini-compatible generateContent / streamGenerateContent |

### Explore the API Documentation

* [Compat generateContent](compat) — Full API reference for the compat endpoint