Gemini API 中转接入：接口地址、API Key 与调用示例

Gemini 有两套请求格式：Google 原生 API（x-goog-api-key 鉴权，请求 /v1beta/interactions 或 /v1beta/models/{model}:generateContent）和 OpenAI 兼容层（Authorization: Bearer 鉴权，请求 /chat/completions）。接 Gemini API 中转前，先看客户端发的是哪一种请求，再填对应的接口地址。两种请求头不能混用。

export GPTZZZ_BASE_URL="https://gptzzz.ai/v1"
export GPTZZZ_API_KEY="YOUR_GPTZZZ_API_KEY"

curl --fail-with-body -sS "$GPTZZZ_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $GPTZZZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-3.8-flash","messages":[{"role":"user","content":"只回复 GEMINI_OK"}],"stream":false}'

$env:GPTZZZ_BASE_URL = "https://gptzzz.ai/v1"
$env:GPTZZZ_API_KEY = "YOUR_GPTZZZ_API_KEY"

$body = @{
  model    = "gemini-3.8-flash"
  messages = @(@{ role = "user"; content = "只回复 GEMINI_OK" })
  stream   = $false
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Method Post -Uri "$env:GPTZZZ_BASE_URL/chat/completions" `
  -Headers @{ Authorization = "Bearer $env:GPTZZZ_API_KEY" } `
  -ContentType "application/json" `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

Gemini API 接口地址

Google 官方有三类地址：原生 Interactions、原生 generateContent 和 OpenAI 兼容层。GPTZZZ 调 Gemini 模型用 OpenAI 兼容入口，没有公布 Gemini 原生入口。

• SDK 的 base_url 只填到 /v1 或 /v1beta/openai/，SDK 会自己追加 /chat/completions。不要再多拼一个 /v1。
• 只有要求填写完整 Endpoint 的客户端，才填 https://gptzzz.ai/v1/chat/completions。
• GPTZZZ 的 API 接入文档和模型价格页只列出 OpenAI 兼容入口 https://gptzzz.ai/v1 和 Claude Messages 入口 https://gptzzz.ai/v1/messages，没有公布 Gemini 原生入口。经 GPTZZZ 调 Gemini 模型，请按 OpenAI 兼容格式发请求，接口地址以控制台当前显示为准；需要原生协议时，直接用 Google 官方地址。
• Google 兼容层除了聊天，还文档化了 Embeddings、图片、视频、Batch 和模型列表接口。GPTZZZ 价格页的 Gemini 分组只列出上表 6 个模型，其他接口以控制台为准。

Gemini 原生 API 与 OpenAI 兼容层怎么选

Google 文档写明：Interactions API 自 2026 年 6 月起正式可用（GA），推荐所有新项目使用，今后的新模型、多模态能力、工具和 Agent 功能都在 Interactions 上发布；原来的 generateContent 现在算旧版接口，但仍完整支持。OpenAI 兼容层仍是 Beta。Google 的建议是：还没在用 OpenAI 库的项目，直接调 Gemini 原生 API。

免费额度与 Google AI Studio

Gemini API 有官方免费层（Free tier），面向入门开发者和小项目。它不是送一笔固定 Token，而是在速率限制内免费调用部分模型。

• 免费模型：Gemini API 官方价格页上，Gemini 3.8 Flash、3.6 Flash、3.5 Flash、3.5 Flash-Lite、3 Flash Preview 等模型的免费层输入、输出都标为 Free of charge；Gemini 3.1 Pro Preview 和图片生成模型在免费层不可用。
• 数据用途：免费层的内容会被用于改进 Google 产品，付费层不会。涉及业务数据时先看条款。
• AI Studio：价格页写明，Google AI Studio 网页内的使用在所有可用地区免费。
• 限额怎么算：按 RPM（每分钟请求数）、TPM（每分钟输入 Token）、RPD（每日请求数）计；按项目累计，不按 Key；RPD 在太平洋时间午夜重置；预览和实验模型的限制更严。
• 具体数值：官方速率限制页不列免费层数字，要在 AI Studio 的 rate limit 页面查看自己项目的当前限额。
• 超限：返回 HTTP 429。Interactions API 的错误码里，rate_limit_exceeded 是每分钟或每秒的请求、Token 超限，quota_exceeded 是日配额用完。
• 升级：给项目绑定有效的结算账号后进入 Tier 1，限额更高，按量计费。

在 Google AI Studio 获取 API Key

1. 打开 Google AI Studio 的 API Key 页面，用 Google 账号登录。
2. 已有 Google Cloud 项目时，先在 Dashboard > Projects 里用 Import projects 导入。
3. 在 API Keys 页面点 Create API key。每个 Key 都属于一个 Google Cloud 项目，结算、成员和权限都在项目上管理。
4. 把 Key 存进环境变量 GEMINI_API_KEY。Google Gen AI SDK 也读 GOOGLE_API_KEY，两个都设置时 GOOGLE_API_KEY 优先。
5. 不要把 Key 写进前端代码，也不要提交到 Git。

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

$env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY"

地区：Google 的 Gemini API 可用地区列表里没有中国大陆、香港和澳门。不在列表内的地区，官方建议改用 Gemini Enterprise Agent Platform 上的 Gemini API。

GPTZZZ 没有免费额度，注册不赠送余额。支付宝充值，单笔 ¥10–¥2000，¥1 = 余额 $1，未用完的余额可以申请退款。所在地区能用官方免费层时，试用先用免费层；需要人民币按量付费、和其他模型共用一份余额时，再看上面的价格表。

Gemini Interactions API：curl 与 Python

这一节是 Google 官方原生调用，用来做基线对照，不经过 GPTZZZ。原生 REST 把 Key 放在 x-goog-api-key 请求头。

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

curl --fail-with-body -sS -X POST \
  "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-3.8-flash","input":"只回复 GEMINI_OK"}'

$env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY"

$body = @{ model = "gemini-3.8-flash"; input = "只回复 GEMINI_OK" } | ConvertTo-Json

Invoke-RestMethod -Method Post -Uri "https://generativelanguage.googleapis.com/v1beta/interactions" `
  -Headers @{ "x-goog-api-key" = $env:GEMINI_API_KEY } `
  -ContentType "application/json" `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

python -m pip install -U google-genai

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="只回复 GEMINI_OK",
)

if interaction.status != "completed" or not interaction.output_text:
    raise RuntimeError(f"unexpected interaction: {interaction}")
print(interaction.output_text)
print({
    "status": interaction.status,
    "model": interaction.model,
    "total_tokens": interaction.usage.total_tokens,
})

成功响应还应核对 object=interaction、steps 中的模型输出和用量。模型与参数会更新，生产配置应同时记录模型 ID、验证日期和 SDK 版本。

Gemini OpenAI 兼容 Python 配置

python -m pip install -U openai

经 GPTZZZ 调用：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GPTZZZ_API_KEY"],
    base_url=os.environ.get("GPTZZZ_BASE_URL", "https://gptzzz.ai/v1"),
)
response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[{"role": "user", "content": "只回复 GEMINI_OK"}],
)
if not response.choices[0].message.content:
    raise RuntimeError(response.model_dump_json())
print(response.model, response.choices[0].message.content)
print(response.usage.total_tokens if response.usage else None)

和 Google 官方兼容层对照时，只换 Key 和 Base URL：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
response = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[{"role": "user", "content": "只回复 GEMINI_OK"}],
)
print(response.choices[0].message.content)

不要在官方 Base URL 后再插入 /v1，也不要把完整 /chat/completions 写进 SDK 的 base_url。

Gemini CLI 接中转

结论：Gemini CLI 发的是 Gemini 原生协议请求，不能直接填 OpenAI 兼容地址，包括 https://gptzzz.ai/v1。

• 官方用法：npm install -g @google/gemini-cli 安装，设置 GEMINI_API_KEY 后运行 gemini。Key 从 AI Studio 获取。按下面提到的 Google 公告，Gemini CLI 继续支持的是付费 API Key，免费层 Key 是否可用公告没有说明。
• 自定义地址：Gemini CLI 配置文档提供 GOOGLE_GEMINI_BASE_URL，在 API Key 认证时覆盖 Gemini API 请求的默认 Base URL。地址必须是 HTTPS，指向 localhost、127.0.0.1 或 [::1] 时除外。
• 协议：Gemini CLI 源码（contentGenerator.ts）用 Google Gen AI SDK 的 models 接口（generateContent 系列）发请求。GOOGLE_GEMINI_BASE_URL 只替换 Base URL，SDK 仍在后面拼接 API 版本（默认 v1beta）和 /models/{model}:generateContent 等原生路径，所以只有实现了 Gemini 原生 API 的网关才能填进去。
• GPTZZZ：接入文档没有公布 Gemini 原生入口，所以本文不给 GPTZZZ 配 Gemini CLI 的写法。要在命令行或编辑器里用 GPTZZZ 的 Gemini 模型，换一个支持 OpenAI 兼容 Base URL 的客户端，填 https://gptzzz.ai/v1 和上表的模型 ID。
• 账号类型：Google 在 2026-05-19 发布的Gemini CLI 迁移公告说明，自 2026-06-18 起，Gemini CLI 不再为 Google AI Pro / Ultra 订阅用户和免费的 Gemini Code Assist 个人版用户提供服务，这些用户转到 Antigravity CLI。Gemini CLI 仍可通过付费的 Gemini API Key 和 Gemini Enterprise Agent Platform API Key 使用；免费层 API Key 是否还能用，公告没有说明。Gemini CLI 认证文档顶部也有这条迁移提示。

官方 API Key 用法，macOS / Linux（bash、zsh）：

npm install -g @google/gemini-cli
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
# 只在网关实现了 Gemini 原生 API 时才设置，且必须是 HTTPS：
# export GOOGLE_GEMINI_BASE_URL="https://your-native-gemini-gateway.example"
gemini

Windows PowerShell：

npm install -g @google/gemini-cli
$env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY"
# 只在网关实现了 Gemini 原生 API 时才设置，且必须是 HTTPS：
# $env:GOOGLE_GEMINI_BASE_URL = "https://your-native-gemini-gateway.example"
gemini

变量也可以写进 .env：Gemini CLI 从当前目录向上找第一个 .env，找不到再读 ~/.gemini/.env（Windows 为 %USERPROFILE%\.gemini\.env）。只读第一个找到的文件，不合并。

Gemini 流式输出与完成事件

from google import genai

stream = genai.Client().interactions.create(
    model="gemini-3.8-flash",
    input="分三点解释 API 中转站",
    stream=True,
)
completed_event = None
for event in stream:
    if event.event_type == "error":
        raise RuntimeError(f"{event.error.code}: {event.error.message}")
    if event.event_type == "step.delta" and event.delta.type == "text":
        print(event.delta.text, end="", flush=True)
    if event.event_type == "interaction.completed":
        completed_event = event

if completed_event is None:
    raise RuntimeError("stream ended without interaction.completed")
interaction = completed_event.interaction
if interaction.status != "completed":
    raise RuntimeError(f"unexpected interaction status: {interaction.status}")
if interaction.usage is None or interaction.usage.total_tokens is None:
    raise RuntimeError("completed interaction has no final usage")
print(f"\nusage.total_tokens={interaction.usage.total_tokens}")

原生 REST 流向 POST /v1beta/interactions 发送请求体 stream: true，curl 使用 --no-buffer 及时读取 SSE；不需要追加未文档化的查询参数。兼容路径则按 Chat Completions 的增量结构消费。两者的结束事件不同，网关若把事件转换为另一种协议，必须验证文本、工具、错误、最终状态与用量都没有丢。

高级功能与参数支持

400、401、404、429 与流内错误

下表是 Google Interactions API 的错误码，官方API 错误码页只覆盖 Interactions API。流式请求里的错误会作为 event_type 为 error 的事件返回。旧版 generateContent 和兼容层的报错格式以各自文档为准；Google 的故障排查页把 429 RESOURCE_EXHAUSTED 和 503 UNAVAILABLE 列为临时错误，建议指数退避后重试。

经 GPTZZZ 兼容入口返回的错误，按 GPTZZZ API 错误码速查排查。协议切换前使用 OpenAI 兼容迁移清单；多模型统一路由参考 多模型 API 网关；SSE 与工具事件用 兼容性测试矩阵；模型别名与上游核对见 模型真实性核验。

Gemini 双协议验证指标与回滚

原生和兼容路径使用同一提示与模型意图，分别记录 HTTP 状态、完成事件、TTFT、总耗时、输出文本哈希、工具成功率、usage.total_tokens 和错误码。兼容率按“同时满足 Schema 与业务断言的用例数 ÷ 全部用例数”计算，而不是只统计 2xx。

1. 停止在途流并保存最后一个事件，避免把半截输出当完整结果。
2. 恢复原生 GEMINI_API_KEY、官方 Endpoint 与已验证模型；不要保留兼容层鉴权头。
3. 关闭 SDK 客户端并在新进程重跑 Interactions 基线。
4. 只有 interaction.completed、用量和业务断言全部恢复后才结束回滚。

官方资料

• Gemini API quickstart
• Gemini Interactions API 概览
• Gemini Interactions API reference
• Gemini Streaming interactions
• Gemini OpenAI compatibility
• Gemini 模型列表
• Gemini API 价格与免费层
• Gemini API 速率限制
• Gemini API 可用地区
• Gemini API keys
• Gemini API errors
• Gemini API troubleshooting
• Gemini CLI GitHub 仓库
• Gemini CLI 迁移到 Antigravity CLI 的公告（2026-05-19）
• Gemini CLI 认证文档
• Gemini CLI 配置参考