# Gemini 系列 API 对接文档

## 基础信息

- 基础域名：`https://api.apiverse.ai`
- 接口路径：`POST https://api.apiverse.ai/v1/gemini/{version}/models/{model}:{streamMode}`
  - `version` 取 `v1beta` 或 `v1beta1`（仅作路径兼容）
  - `streamMode` 取 `generateContent`（非流式）或 `streamGenerateContent?alt=sse`（流式）
- 鉴权方式：`Authorization: Bearer <API_KEY>`
- Content-Type：`application/json`
- 协议：**兼容 Google Gemini 标准协议**，可直接复用官方 SDK，仅需替换 `base_url` 与 `api_key`。

## 鉴权说明

- 所有接口均使用 Bearer Token（API Key）鉴权，请在请求头携带：

  ```
  Authorization: Bearer <API_KEY>
  ```

- API Key 在控制台「API 密钥」页面创建，需在创建时开通「大模型」能力后方可调用本组接口。
- 若使用未开通大模型能力的 Key 调用，会返回 `403`：

  ```json
  {
    "error": {
      "message": "该 API Key 尚未开通 LLM 能力，请在控制台重新创建 API Key 完成开通",
      "type": "permission_error"
    }
  }
  ```

## 支持的模型

### 文本 / 多模态理解

| 模型 | 模型参数（model） |
| ---- | ---- |
| Gemini 3.7 Flash | gemini-3.7-flash |
| Gemini 3.6 Flash | gemini-3.6-flash |
| Gemini 3.5 Flash | gemini-3.5-flash |
| Gemini 3.5 Flash Lite | gemini-3.5-flash-lite |
| Gemini 3.1 Pro Preview | gemini-3.1-pro-preview |
| Gemini 3.1 Flash Lite | gemini-3.1-flash-lite |
| Gemini 3.1 Flash Lite Preview | gemini-3.1-flash-lite-preview |
| Gemini 3 Flash | gemini-3-flash-preview |
| Gemini 2.5 Pro | gemini-2.5-pro |
| Gemini 2.5 Flash | gemini-2.5-flash |

### 图像生成

| 模型 | 模型参数（model） |
| ---- | ---- |
| Nano Banana 2 Preview | gemini-3.1-flash-image-preview |
| Nano Banana 2 | gemini-3.1-flash-image |
| Nano Banana Pro | gemini-3-pro-image |
| Nano Banana | gemini-2.5-flash-image |

> 实际可调用的模型以你的账户已开通的资源为准。完整模型清单、上下文长度与单价请以控制台「模型广场」「定价」页面展示为准，请勿硬编码猜测模型名。

## 调用方式

### cURL

```bash
curl -X POST "https://api.apiverse.ai/v1/gemini/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"type": "text", "text": "你好，哥们"}]}
    ]
  }'
```

### 请求体（多轮对话 + 系统指令）

```json
{
    "model": "gemini-3.1-pro-preview",
    "stream": true,
    "contents": [
        {
            "role": "user",
            "parts": [
                {"type": "text", "text": "你好，哥们"}
            ]
        },
        {
            "role": "assistant",
            "parts": [
                {"type": "text", "text": "嘿，哥们！你好啊！有什么可以帮你的吗？"}
            ]
        },
        {
            "role": "user",
            "parts": [
                {"type": "text", "text": "作一首诗吧"}
            ]
        }
    ],
    "systemInstruction": {
        "parts": [{"text": "你假装自己是老子，所有回答尽量依靠道德经等内容"}]
    }
}
```

## 图像生成（Nano Banana 系列）

以 Gemini 协议调用图像模型时，注意以下三点：

1. **`stream` 必须不传或传 `false`**。
2. **`imageConfig`**
   - `aspectRatio`：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`；
     Nano Banana 2（`gemini-3.1-flash-image`）额外支持 `1:4`、`4:1`、`1:8`、`8:1`。
   - `imageSize`：`512`（仅 Nano Banana 2）、`1k`、`2k`、`4k`。
   - Nano Banana 2 的 `4k` 与 `1:8`、`1:4` 这类极端比例组合稳定性较差，无特殊需求不建议这么传。
3. **参考图**：在 `parts` 中以 base64 追加多个图片块，数量不宜过多。

```json
{
    "model": "gemini-3-pro-image",
    "stream": false,
    "generationConfig": {
        "responseModalities": ["TEXT", "IMAGE"],
        "imageConfig": {
            "aspectRatio": "21:9",
            "imageSize": "4k"
        }
    },
    "contents": [
        {
            "role": "user",
            "parts": [
                {"type": "text", "text": "画一只好看的小猫"},
                {
                    "type": "image",
                    "inlineData": {
                        "mimeType": "image/jpeg",
                        "data": "<替换为真实的 base64 图片数据>"
                    }
                }
            ]
        }
    ]
}
```

> `mimeType` 也可用 `image/png`。生成 4K 图片耗时较长，客户端与代理请把 HTTP 超时调大（建议 ≥ 10 分钟）。

## 计费说明

- 文本模型按 **token 用量**计费，通常区分输入 / 输出，部分模型另有缓存读写、思考（thinking）、多模态图片等维度，不同模型单价不同。
- **各模型的具体单价与计价维度，请以控制台「定价」页面展示为准。**
- 每次调用的 token 用量以响应中的 `usage` 字段为准；账户维度的用量、账单与消费汇总可在控制台「用量」「账单」页面查看，并支持导出。
- 文本模型消费在账户余额中结算，调用前请确保余额充足（余额可通过「余额查询 API」查询）。

## 错误码说明

| 状态码 | 说明 | 解决方案 |
| ------ | ---- | -------- |
| 401 | 未授权 / API Key 无效 | 检查 `Authorization` 头与 API Key 是否正确 |
| 403 | API Key 未开通大模型能力 | 在控制台重新创建并开通大模型能力的 API Key |
| 429 | 触发限流或上游繁忙 | 退避后重试；持续出现请联系技术支持 |
| 666 | 模型调用相关异常（统一错误码） | 复制响应体中的 `code_reason` 联系技术支持 |
| 5xx | 服务内部异常 | 稍后重试或联系技术支持 |

模型调用类异常统一以 HTTP 状态码 `666` 返回，响应体形如：

```json
{
  "code": 9000,
  "code_msg": "服务器异常",
  "code_reason": "具体原因，排查时请连同该字段一起提供"
}
```

其余错误响应结构遵循所用协议的标准格式，例如 OpenAI 兼容协议：

```json
{
  "error": {
    "message": "invalid api key",
    "type": "invalid_request_error",
    "code": "401"
  }
}
```

## 注意事项

1. **协议一致**：请优先使用官方 SDK 与官方请求体，跨协议转写存在字段不兼容风险。
2. **图像模型不支持流式**：`stream` 传 `true` 会导致请求失败。
3. **偶发 429**：Gemini 系列在高峰期可能返回 `429`，退避后重试即可。
4. **模型名以广场为准**：调用前请在「模型广场」确认当前可用的模型名称。