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.

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.

Why Use Compat API?

Official SDK Support

Works with Google’s official @google/genai (TypeScript) and google-genai (Python) libraries

Same API Shape

Uses the same generateContent / streamGenerateContent endpoints and request/response schema

Unified Billing

Single API key, unified usage tracking and billing through Mountsea

Image Generation

Supports image generation via gemini-*-image models (auto-routed to Nano Banana)

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`

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.

Using the Official @google/genai SDK

Installation

npm install @google/genai

pnpm add @google/genai

yarn add @google/genai

pip install google-genai

TypeScript / JavaScript

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);

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 ?? '');
}

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);
  }
}

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'));
}

Python

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)

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)

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)

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

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

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:

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:

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"`

Both camelCase (aspectRatio, imageSize) and snake_case (aspect_ratio, image_size) are accepted. These fields can also be placed directly on generationConfig as shortcuts.

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

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.

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 — Full API reference for the compat endpoint

​Gemini Compat API

​Why Use Compat API?

Official SDK Support

Same API Shape

Unified Billing

Image Generation

​Configuration

​Base URL

​Authentication

​Image Model Mapping

​Using the Official @google/genai SDK

​Installation

​TypeScript / JavaScript

​Python

​Using the Gemini REST API

​Endpoint

​Text Generation

​Image Generation

​Image Editing

​Streaming

​Image Generation Config

​Supported Aspect Ratios (by Model)

​Notes & Limitations

​Available Endpoint

​Explore the API Documentation

Gemini Compat API

Why Use Compat API?

Configuration

Base URL

Authentication

Image Model Mapping

Using the Official @google/genai SDK

Installation

TypeScript / JavaScript

Python

Using the Gemini REST API

Endpoint

Text Generation

Image Generation

Image Editing

Streaming

Image Generation Config

Supported Aspect Ratios (by Model)

Notes & Limitations

Available Endpoint

Explore the API Documentation