跳到主要内容

Gemini 原生接口

Gemini 原生接口适用于 Google Gen AI SDK，以及明确要求 Gemini generateContent 请求格式的应用。它使用 /v1beta 路径，并将模型 ID 放在请求地址中。

接口信息​

项目内容
请求方法POST
完整地址格式https://www.bita-api.com/v1beta/models/MODEL_ID:generateContent
常用根地址https://www.bita-api.com
鉴权方式x-goog-api-key: YOUR_BITA_API_KEY
请求格式application/json

请先在模型广场确认目标模型支持 Gemini 端点，或通过 /v1beta/models 查询当前密钥可用的 Gemini 格式模型。

确认模型 ID​

Gemini 模型列表中的 name 可能采用下面的格式：

models/YOUR_MODEL_ID

拼接调用地址时只保留一个 models/：

https://www.bita-api.com/v1beta/models/YOUR_MODEL_ID:generateContent

不要拼成 /models/models/YOUR_MODEL_ID:generateContent。

发送请求​

将 YOUR_BITA_API_KEY 和地址中的 YOUR_MODEL_ID 替换为自己的信息。示例需要先安装 requests：python -m pip install requests。

import requests

response = requests.post(
    "https://www.bita-api.com/v1beta/models/YOUR_MODEL_ID:generateContent",
    headers={"x-goog-api-key": "YOUR_BITA_API_KEY"},
    json={
        "contents": [
            {
                "role": "user",
                "parts": [
                    {
                        "text": "请用一句话介绍 Bita API。",
                    }
                ],
            }
        ]
    },
    timeout=120,
)
response.raise_for_status()

result = response.json()
for candidate in result.get("candidates", []):
    for part in candidate.get("content", {}).get("parts", []):
        if "text" in part:
            print(part["text"])

请求结构​

字段是否必填说明
contents是对话内容数组
contents[].role建议填写常见值为 user 或 model
contents[].parts是当前消息的内容块数组
parts[].text文本请求需要文本内容
generationConfig否温度、最大输出长度等生成配置，支持情况以模型为准

需要连续对话时，把历史内容按顺序放入 contents，并使用 user 和 model 角色交替表示双方消息。

读取响应​

响应通常类似：

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Bita API 提供统一的模型 API 接入服务。"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 0,
    "candidatesTokenCount": 0,
    "totalTokenCount": 0
  }
}

重点字段：

  • candidates：候选结果数组。
  • candidates[0].content.parts：候选结果的内容块。
  • parts[].text：文本内容。
  • finishReason：生成停止原因，正常完成通常为 STOP。
  • usageMetadata：输入、输出和总 Token 用量。

生产代码应检查 candidates 是否存在，并根据内容块结构读取结果。受到安全策略拦截或模型没有生成文本时，响应可能不包含预期的文本字段。

两种密钥传递方式​

Gemini 兼容接口可能支持以下两种形式：

x-goog-api-key: YOUR_BITA_API_KEY
?key=YOUR_BITA_API_KEY

推荐使用 x-goog-api-key 请求头。查询参数可能被浏览器历史、代理或访问日志记录，不适合长期使用。

常见问题​

现象建议检查
401 或 403x-goog-api-key、密钥状态、分组和额度
404是否使用 /v1beta，模型 ID 是否正确，路径中是否重复 models/
模型不支持生成模型列表中的 supportedGenerationMethods 是否包含 generateContent
请求体格式错误contents、parts 是否均为数组，文本是否位于 parts[].text
没有返回文本检查 candidates、finishReason 以及响应中的安全相关信息
模型供应商不等于接口格式

模型名称中包含 Gemini，不代表必须使用 Gemini 原生接口；同样，其他来源的模型也可能提供 Gemini 兼容格式。应以模型广场标注的端点类型和第三方工具要求为准。

下一步：流式响应。