Gemini 系列

查看 Markdown 原文

基础信息

  • 基础域名：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：
  {
    "error": {
      "message": "该 API Key 尚未开通 LLM 能力，请在控制台重新创建 API Key 完成开通",
      "type": "permission_error"
    }
  }
  ```

支持的模型

文本 / 多模态理解

模型模型参数（model）
Gemini 3.7 Flashgemini-3.7-flash
Gemini 3.6 Flashgemini-3.6-flash
Gemini 3.5 Flashgemini-3.5-flash
Gemini 3.5 Flash Litegemini-3.5-flash-lite
Gemini 3.1 Pro Previewgemini-3.1-pro-preview
Gemini 3.1 Flash Litegemini-3.1-flash-lite
Gemini 3.1 Flash Lite Previewgemini-3.1-flash-lite-preview
Gemini 3 Flashgemini-3-flash-preview
Gemini 2.5 Progemini-2.5-pro
Gemini 2.5 Flashgemini-2.5-flash

图像生成

模型模型参数（model）
Nano Banana 2 Previewgemini-3.1-flash-image-preview
Nano Banana 2gemini-3.1-flash-image
Nano Banana Progemini-3-pro-image
Nano Bananagemini-2.5-flash-image
实际可调用的模型以你的账户已开通的资源为准。完整模型清单、上下文长度与单价请以控制台「模型广场」「定价」页面展示为准，请勿硬编码猜测模型名。

调用方式

cURL

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": "你好，哥们"}]}
    ]
  }'

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

{
    "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
  3. aspectRatio：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9；
  4. Nano Banana 2（gemini-3.1-flash-image）额外支持 1:4、4:1、1:8、8:1。
  5. imageSize：512（仅 Nano Banana 2）、1k、2k、4k。
  6. Nano Banana 2 的 4k 与 1:8、1:4 这类极端比例组合稳定性较差，无特殊需求不建议这么传。
  7. 参考图：在 parts 中以 base64 追加多个图片块，数量不宜过多。
{
    "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 是否正确
403API Key 未开通大模型能力在控制台重新创建并开通大模型能力的 API Key
429触发限流或上游繁忙退避后重试；持续出现请联系技术支持
666模型调用相关异常（统一错误码）复制响应体中的 code_reason 联系技术支持
5xx服务内部异常稍后重试或联系技术支持

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

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

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

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

注意事项

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