Gemini Native

Gemini 原生接口使用 /v1beta/models/{model}:generateContent 路径和 x-goog-api-key 请求头。

curl 示例

bash

# 模型 ID 位于 URL 中，末尾的 :generateContent 不能省略。
curl "https://sprelaytoken.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $SPRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {"text": "用一句话解释什么是 API 网关。"}
        ]
      }
    ]
  }'

x-goog-api-key 直接携带 Sprelay 密钥；contents 是消息数组；parts 是一条消息中的内容块。JSON 不支持注释，修改提示词时只改 text 的值。

模型名称仅为示例，请从当前模型列表复制可用名称。

Python 原生 HTTP 示例

python

# os 读取密钥，requests 用于发送普通 HTTP 请求。
import os
import requests

# 模型名称会嵌入 URL；请替换为模型列表中的完整 ID。
model = "gemini-3-flash-preview"
url = f"https://sprelaytoken.com/v1beta/models/{model}:generateContent"

# headers 传鉴权信息，json 传请求正文，timeout 防止无限等待。
response = requests.post(
    url,
    headers={
        "x-goog-api-key": os.environ["SPRELAY_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "contents": [
            {
                "role": "user",
                "parts": [{"text": "用一句话解释什么是 API 网关。"}],
            }
        ]
    },
    timeout=60,
)
# 非 2xx 响应会在这里抛出异常，避免把错误正文当成成功结果。
response.raise_for_status()

# 先打印完整 JSON 便于学习结构；正式程序通常读取 candidates 内容。
print(response.json())

返回内容

文本通常位于：

text

candidates[0].content.parts[0].text

生产代码应处理空候选、内容安全拦截和多个 parts，不要只假设固定数组长度。

与 OpenAI Compatible 的区别

Gemini 模型可能同时提供 OpenAI Compatible 和 Gemini Native 入口。两者请求结构不同：

OpenAI Compatible 使用 /v1/chat/completions 与 messages。
Gemini Native 使用 /v1beta/models/...:generateContent 与 contents/parts。

沿用现有项目的协议即可，不需要为了模型名称改写整套代码。

常见错误

404：检查路径中是否包含 :generateContent。
401：确认 x-goog-api-key 是完整 Sprelay 密钥。
模型不存在：先调用 GET /v1beta/models。
503 或 No available Gemini accounts：当前上游线路没有可用账户，或渠道价格限制不匹配。不要无限重试；请稍后再试，并结合模型广场与使用日志确认实时可用性。
正文解析失败：确认发送的是 contents，不是 OpenAI 的 messages。

Gemini Native ​

curl 示例 ​

Python 原生 HTTP 示例 ​

返回内容 ​

与 OpenAI Compatible 的区别 ​