> ## 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 兼容接口

**Gemini 兼容接口** 是 Google 官方 Gemini API 的 **直接替代**。完全兼容官方 **@google/genai** SDK 及 Gemini REST 接口 —— 只需修改 Base URL 和 API Key，即可无缝切换。

<Tip>
  **无需修改代码** —— 如果您已经使用 `@google/genai` 或调用 Gemini REST API，只需将 SDK 指向 `https://api.mountsea.ai/gemini`，使用 Mountsea API Key 即可。
</Tip>

## 为什么使用兼容接口？

<CardGroup cols={2}>
  <Card title="官方 SDK 支持" icon="code">
    完美兼容 Google 官方 `@google/genai`（TypeScript）与 `google-genai`（Python）库
  </Card>

  <Card title="接口形状一致" icon="equals">
    使用相同的 `generateContent` / `streamGenerateContent` 端点和请求/响应结构
  </Card>

  <Card title="统一计费" icon="wallet">
    一个 API Key 即可，通过 Mountsea 统一跟踪用量和计费
  </Card>

  <Card title="图像生成" icon="image">
    通过 `gemini-*-image` 模型 ID 进行图像生成（自动路由到 Nano Banana）
  </Card>
</CardGroup>

## 配置

### Base URL

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

### 鉴权

使用您的 **Mountsea API Key**（Bearer token），支持以下两种方式：

* HTTP 头部：`Authorization: Bearer your-api-key`
* 或通过官方 SDK 的 `apiKey` 参数传入

## 图像模型映射

当使用图像模型 ID 调用兼容接口时，会自动路由到对应的 Nano Banana 模型：

| Gemini 模型 ID（输入）                 | 路由到（Nano Banana） |
| -------------------------------- | ---------------- |
| `gemini-2.5-flash-image`         | `NanoBananaFast` |
| `gemini-3.1-flash-image-preview` | `NanoBanana2`    |
| `gemini-3-pro-image-preview`     | `NanoBananaPro`  |

<Info>
  您可以使用 **上表中的 Gemini 模型 ID**，也可以直接使用原生 Nano Banana 模型 ID（`nano-banana-fast`、`nano-banana-2`、`nano-banana-pro`）—— 两种方式均支持。
</Info>

***

## 使用官方 @google/genai SDK

### 安装

<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 文本生成 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: '用一段话解释量子计算',
  });

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

  ```typescript 流式输出 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: '写一首关于大海的短诗',
  });

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

  ```typescript 图像生成 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: '夜晚的未来城市天际线，霓虹灯倒映在湿漉漉的街道上',
    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 图像编辑 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: '给画面加上飘落的雪花' },
          {
            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 文本生成 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="用一段话解释量子计算",
  )
  print(response.text)
  ```

  ```python 流式输出 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="写一首关于大海的短诗",
  )

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

  ```python 图像生成 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="夜晚的未来城市天际线",
      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>

***

## 使用 Gemini REST API

如果不使用 SDK，也可以直接调用 REST 接口。请求结构与 Google 官方 REST API 完全一致。

### 端点

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

其中：

* `{model}` —— 模型 ID（例如 `gemini-2.5-flash`、`gemini-3-pro-image-preview`）
* `{action}` —— `generateContent`（JSON 响应）或 `streamGenerateContent`（SSE 流）

### 文本生成

```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": "用一段话解释量子计算" }]
      }
    ]
  }'
```

### 图像生成

```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": "夜晚的未来城市天际线" }]
      }
    ],
    "generationConfig": {
      "responseModalities": ["image", "text"],
      "imageConfig": {
        "aspectRatio": "16:9",
        "imageSize": "2K"
      }
    }
  }'
```

### 图像编辑

在 `parts` 数组中通过 `inline_data` 传入参考图：

```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": "给画面加上飘落的雪花" },
          {
            "inline_data": {
              "mime_type": "image/jpeg",
              "data": "<base64 编码的图片字节>"
            }
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["image"],
      "imageConfig": { "aspectRatio": "1:1" }
    }
  }'
```

### 流式输出

将 `generateContent` 改为 `streamGenerateContent` 即可接收 Server-Sent Events（SSE）流：

```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": "写一首短诗" }] }
    ]
  }'
```

***

## 图像生成配置

当请求图像生成（`response_modalities` 包含 `image`）时，可以配置输出：

| 字段                             | 位置                             | 说明  | 示例                        |
| ------------------------------ | ------------------------------ | --- | ------------------------- |
| `aspectRatio` / `aspect_ratio` | `generationConfig.imageConfig` | 宽高比 | `"1:1"`、`"16:9"`、`"9:16"` |
| `imageSize` / `image_size`     | `generationConfig.imageConfig` | 分辨率 | `"1K"`、`"2K"`、`"4K"`      |

<Info>
  同时支持 camelCase（`aspectRatio`、`imageSize`）和 snake\_case（`aspect_ratio`、`image_size`）。这些字段也可以作为快捷方式直接放在 `generationConfig` 上。
</Info>

### 各模型支持的宽高比

* **`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）：所有标准宽高比
* **`gemini-3.1-flash-image-preview`**（→ NanoBanana2）：所有标准宽高比 + `1:4`、`4:1`、`1:8`、`8:1`

***

## 注意事项与限制

<Warning>
  目前兼容接口每次请求只返回 **1 张图像**。为兼容而接收的 `candidateCount` 字段不参与逻辑，实际按 1 处理。
</Warning>

* 图像生成时，请务必在 `generationConfig` 中加入 `responseModalities: ["image"]`（或 `["image", "text"]`）。
* `inline_data.data` 字段应为原始 base64（不带 `data:*;base64,` 前缀）。
* `inline_data`（snake\_case）和 `inlineData`（camelCase）均受支持。

***

## 可用端点

| 端点                                    | 方法   | 描述                                                  |
| ------------------------------------- | ---- | --------------------------------------------------- |
| `/gemini/v1beta/models/{modelAction}` | POST | Gemini 兼容接口 generateContent / streamGenerateContent |

### 浏览 API 文档

* [兼容接口 generateContent](compat) —— 完整的 API 参考