Gemini 原生协议 API 参考

    通过 Gate.AI Gemini 原生协议调用 Gemini 模型。适合已经使用 Gemini contents\\\、parts\\\、tools\\\ 请求结构的应用。

    字段值
    Base URLhttps://api.gate.ai/gemini/v1beta
    认证Authorization: Bearer <API_KEY>
    格式Gemini 原生 JSON 请求体
    文本生成POST /models/{model}:generateContent
    流式生成POST /models/{model}:streamGenerateContent?alt=sse

    Gate.AI 使用自己的 API Key，不使用 Google Gemini 的 ?key= 参数。
    Gemini 原生协议通过 URL path 中的 {model} 指定模型，例如 POST /models/gemini-2.5-pro:generateContent。请求 body 无需再次传入 model。这与 OpenAI Chat Completions 在请求 body 中传入 model 的方式不同。

    Base URL 等效路径

    场景Base URL
    Gate.AI 显式指定 Gemini 协议（推荐）https://api.gate.ai/gemini/v1beta
    Google AI Studio SDK 直接接入（去掉 /gemini 前缀）https://api.gate.ai/v1beta
    Vertex AI 风格路径（带前缀）https://api.gate.ai/gemini/v1/publishers/google/models/{model}:{action}
    Vertex AI 风格路径（去前缀）https://api.gate.ai/v1/publishers/google/models/{model}:{action}

    文本生成

    POST/models/{model}:generateContent

    根据 Gemini 原生 contents\\\ 请求体生成模型回复。

    请求参数

    名称位置类型必选说明
    Authorizationheaderstring是Gate.AI API Key。格式：Bearer <API_KEY>
    Content-Typeheaderstring是请求体格式：application/json
    modelpathstring是Gemini 模型 ID，如 gemini-2.5-pro

    请求体

    名称类型必选说明
    contentsarray是Gemini 对话内容，按轮次顺序排列
    contents\\\.rolestring否user 或 model
    contents\\\.partsarray是一轮消息中的内容片段
    parts\\\.textstring否文本输入
    parts\\\.inlineDataobject否多模态输入，包含 mimeType 和 base64 data
    toolsarray否工具声明，使用 Gemini functionDeclarations 格式
    toolConfigobject否工具调用策略
    generationConfigobject否生成参数，如 temperature、maxOutputTokens
    systemInstructionobject否系统指令

    示例

    bash
    1export GATEAI_API_KEY="sk-v1-xxxxxxxxxxxxxxxx"23curl https://api.gate.ai/gemini/v1beta/models/gemini-2.5-pro:generateContent \4  -H "Authorization: Bearer $GATEAI_API_KEY" \5  -H "Content-Type: application/json" \6  -d '{7    "contents": [8      {9        "role": "user",10        "parts": [11          {"text": "Introduce Gate.AI in one sentence"}12        ]13      }14    ]15  }'

    返回字段说明

    名称类型说明
    candidatesarray模型候选回复
    candidates\\\.indexinteger候选索引，从 0 开始
    candidates\\\.content.rolestring固定为 model
    candidates\\\.content.parts\\\.textstring文本回复内容
    candidates\\\.content.parts\\\.thoughtboolean是否为模型的思考内容（reasoning）
    candidates\\\.content.parts\\\.thoughtSignaturestring思考内容签名，用于多轮 reasoning 上下文延续
    candidates\\\.content.parts\\\.functionCallobject工具调用请求
    candidates\\\.finishReasonstring结束原因，如 STOP
    usageMetadataobject用量与计费信息
    usageMetadata.promptTokenCountinteger输入 token 数
    usageMetadata.candidatesTokenCountinteger输出 token 数
    usageMetadata.totalTokenCountinteger总 token 数
    usageMetadata.coststring本次请求费用，单位 USD

    返回示例

    json
    1{2  "candidates": [3    {4      "index": 0,5      "content": {6        "role": "model",7        "parts": [8          {9            "text": "Gate.AI is a unified AI model routing platform."10          }11        ]12      },13      "finishReason": "STOP"14    }15  ],16  "usageMetadata": {17    "promptTokenCount": 13,18    "candidatesTokenCount": 37,19    "totalTokenCount": 50,20    "cost": "0.0000964"21  }22}

    流式生成

    POST/models/{model}:streamGenerateContent?alt=sse

    流式返回 Gemini 响应片段。最后一段通常包含 usageMetadata。客户端按 Gemini 流式协议读取 candidates\\\.content.parts\\\.text 即可。

    请求参数

    名称位置类型必选说明
    Authorizationheaderstring是Gate.AI API Key。格式：Bearer <API_KEY>
    Content-Typeheaderstring是请求体格式：application/json
    modelpathstring是Gemini 模型 ID，如 gemini-2.5-pro

    请求体

    名称类型必选说明
    contentsarray是Gemini 对话内容，按轮次顺序排列
    contents\\\.rolestring否user 或 model
    contents\\\.partsarray是一轮消息中的内容片段
    parts\\\.textstring否文本输入
    parts\\\.inlineDataobject否多模态输入，包含 mimeType 和 base64 data
    toolsarray否工具声明，使用 Gemini functionDeclarations 格式
    toolConfigobject否工具调用策略
    generationConfigobject否生成参数，如 temperature、maxOutputTokens
    systemInstructionobject否系统指令

    示例

    bash
    1curl -N "https://api.gate.ai/gemini/v1beta/models/gemini-2.5-pro:streamGenerateContent?alt=sse" \2  -H "Authorization: Bearer $GATEAI_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "contents": [6      {7        "role": "user",8        "parts": [9          {"text": "List three scenarios where model routing is useful"}10        ]11      }12    ]13  }'

    多模态输入

    图片、音频、视频、PDF 等内容放入同一个 parts[]。Gate.AI Gemini 入口建议使用 camelCase 字段：inlineData.mimeType。

    类型mimeType 示例
    图片image/png、image/jpeg
    音频audio/mp3、audio/wav
    视频video/mp4
    PDFapplication/pdf

    图片输入示例

    ini
    1IMAGE_B64="$(base64 -i ./image.png | tr -d '\n')"23curl https://api.gate.ai/gemini/v1beta/models/gemini-2.5-pro:generateContent \4  -H "Authorization: Bearer $GATEAI_API_KEY" \5  -H "Content-Type: application/json" \6  -d "{7    \"contents\": [8      {9        \"role\": \"user\",10        \"parts\": [11          {\"text\": \"描述这张图片\"},12          {13            \"inlineData\": {14              \"mimeType\": \"image/png\",15              \"data\": \"${IMAGE_B64}\"16            }17          }18        ]19      }20    ]21  }"

    工具调用

    Gemini 工具使用 tools[].functionDeclarations[]。工具策略放在 toolConfig.functionCallingConfig。

    json
    1{2  "contents": [3    {4      "role": "user",5      "parts": [6        {"text": "北京今天适合穿什么?"}7      ]8    }9  ],10  "tools": [11    {12      "functionDeclarations": [13        {14          "name": "get_weather",15          "description": "查询城市天气",16          "parameters": {17            "type": "object",18            "properties": {19              "city": {20                "type": "string",21                "description": "城市名"22              }23            },24            "required": ["city"]25          }26        }27      ]28    }29  ],30  "toolConfig": {31    "functionCallingConfig": {32      "mode": "AUTO"33    }34  }35}

    模型触发工具时，会在 candidates[].content.parts[] 返回 functionCall。

    状态码

    状态码状态码含义说明
    200OK请求成功
    400Bad Request请求体错误、JSON 无效，或缺少必要的 contents / parts
    401UnauthorizedAPI Key 无效或缺失
    402Payment Required余额不足
    404Not FoundAPI 路径错误、模型不存在，或模型未启用该协议
    413Payload Too Large多模态请求体过大
    429Too Many Requests请求过于频繁，请降低调用频率
    500Internal Server Error服务内部错误
    502Bad Gateway上游 Gemini 服务失败

    和 OpenAI 兼容接入的区别

    如果应用已经使用 OpenAI Chat Completions，可以继续通过 https://api.gate.ai/openai/v1/chat/completions 调用 Gemini 模型。如果应用已经使用 Gemini 原生 contents\\\ / parts\\\ 格式，使用本页的 /gemini/v1beta/models/... 端点，迁移成本更低。

    常见问题

    现象原因处理建议
    404路径缺少 /gemini/v1beta 或模型 ID 错误使用 https://api.gate.ai/gemini/v1beta/models/{model}:generateContent
    多模态内容读不到inlineData 字段名、MIME 或 base64 不正确使用 inlineData.mimeType/data，确认 base64 不带换行
    工具没有触发schema 超出 Gemini 支持的 JSON Schema 子集先使用 type、properties、required、description 等基础字段