Gemini (Google AI Studio)

Google Gemini 是可通过 Google AI Studio 和 Google Cloud Vertex AI 使用的多模态模型系列。本指南将 Google AI Studio 端点接入 AISIX，使应用能够通过网关管理的凭证、访问控制、速率限制和用量核算来调用 Gemini。

本指南使用 Google AI Studio 端点。如需改为通过 Google Cloud 路由 Gemini，请使用 Google Vertex AI。

准备工作

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
• 从 Google AI Studio 获取的 Google AI Studio API Key。
• curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且不含尾部斜杠
# 本地私有化部署快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

为以 Gemini 为后端的 Chat Completions 路由创建服务提供方密钥、模型别名和调用方 API Key。

由于 Google AI Studio 提供兼容 OpenAI 的端点，AISIX 通过 openai 适配器连接，并将 Google AI Studio API 根地址用作 api_base。

创建服务提供方密钥

创建用于存储 Google AI Studio 凭证和 API 根地址的服务提供方密钥，并允许该环境使用此密钥：

# 请替换为实际值
export GEMINI_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "${AISIX_CP}/provider_keys" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gemini-prod",
    "provider": "google",
    "api_key": "'"${GEMINI_API_KEY}"'",
    "api_base": "https://generativelanguage.googleapis.com/v1beta/openai",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "${PROVIDER_KEY_ID}"

❶ provider 为 google，即 Google AI Studio 的目录服务提供方 ID。AISIX Cloud Admin API 会从目录服务提供方推导适配器；只有 BYO 服务提供方密钥才接受 adapter 字段。

❷ api_key 存储 Google AI Studio API Key。该值遵循服务提供方密钥中的凭证处理行为。

❸ 对于此目录服务提供方，api_base 是可选字段，因为省略时 AISIX Cloud Admin API 会填入相同的值。显式设置该字段可使上游根地址在资源中保持可见。请使用末尾不带斜杠的根地址；AISIX 会向其追加 /chat/completions。

该命令会把返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

创建调用方将在请求中发送的模型别名：

MODEL_ID=$(curl -sS -X POST "${AISIX_CP}/environments/${ENV_ID}/models" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gemini-flash-prod",
    "model_name": "gemini-3.6-flash",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "${MODEL_ID}"

❶ display_name 是调用方在 model 中发送的别名。

❷ model_name 是 Gemini 模型 ID，例如 gemini-3.6-flash。请从 Gemini 模型页面选择稳定 ID，并在部署前检查其生命周期；Google 会按照公布的计划停用旧的稳定版和预览版 ID。

❸ provider_key_id 将别名关联到 Gemini 服务提供方密钥。

创建调用方 API Key

创建可访问该模型别名的调用方 API Key 资源。服务器会生成密钥值，并仅在响应中返回一次明文：

AISIX_API_KEY=$(curl -sS -X POST "${AISIX_CP}/environments/${ENV_ID}/api_keys" \
  -H "Authorization: Bearer ${AISIX_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gemini-app",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "${AISIX_API_KEY}"

allowed_models 的值通过 ID 引用模型。请安全存储明文密钥；之后无法再次获取。

新资源会自动投射到已关联的网关。

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export GEMINI_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

对于新网关，请使用以下完整的声明式资源文件。对于现有网关，请把这些条目合并到当前文件，并保留其他资源：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "gemini-prod"
    provider: "google"
    adapter: "openai"
    api_key: ${GEMINI_API_KEY}
    api_base: "https://generativelanguage.googleapis.com/v1beta/openai"

models:
  - display_name: "gemini-flash-prod"
    provider: "google"
    model_name: "gemini-3.6-flash"
    provider_key: "gemini-prod"

api_keys:
  - display_name: "gemini-app"
    key_env: CALLER_API_KEY
    allowed_models:
      - "gemini-flash-prod"

如果 AISIX 安装在本地，请在加载前验证文件：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件引用的环境变量，再启动网关。仅当这些变量已经可供进程使用时，才重新加载现有网关；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的验证和启动命令。挂载此 resources.yaml 文件，并在两条命令中使用 -e 传入它引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# AISIX_PROXY 不含尾部斜杠或端点路径
# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"

通过 AISIX 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-flash-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Gemini."
      }
    ]
  }'

网关返回兼容 OpenAI 的响应，其中会回显面向调用方的别名 gemini-flash-prod。如果请求失败，请检查服务提供方密钥的 api_key、api_base，以及 model_name 中的 Gemini 模型 ID。

使用 Gemini 思考和工具

Google 的 OpenAI 兼容 Chat 端点接受 reasoning_effort。AISIX 会原样转发该字段及其他未建模的顶层字段，因此调用方可以使用所选 Gemini 模型支持的强度：

{
  "model": "gemini-flash-prod",
  "messages": [{"role": "user", "content": "Plan a safe database migration."}],
  "reasoning_effort": "medium"
}

extra_body.google 下的 Gemini 专用控制项（例如 thinking_config）也会透传。不要在同一请求中同时发送 reasoning_effort 和 Google 的思考强度或思考预算控制项，因为它们配置的是同一行为。对于 gemini-3.6-flash 及更新模型，请移除 temperature、top_p 和 top_k 等已弃用的采样字段；AISIX 会转发这些字段，而不会代替你移除。

Gemini 3 工具调用在 tool_calls[].extra_content.google.thought_signature 中携带必需的思考签名。在 /v1/chat/completions 上继续函数调用轮次时，请保留完整的助手 tool_calls 对象，并将其与工具结果一起原样发回。AISIX 会保留这些原始对象，但不会管理应用的对话状态。

多步 Gemini 3 工具循环不要使用 /v1/responses 或转换后的 /v1/messages 路由。这些桥接会重建可移植的工具调用字段，而不会重放 Google 专用思考签名，因此下一次 Gemini 请求可能因验证错误返回 400。请参阅 OpenAI 兼容性的思考签名。

查看端点支持情况

Google AI Studio OpenAI 兼容 API 提供的路由多于 AISIX 当前为 google 服务提供方建模的路由。请选择同时满足两层约束的路由：

路由	使用 google 服务提供方密钥时的行为
/v1/chat/completions	支持，包括流式传输，以及所选模型接受的多模态图像、音频或视频输入。
/v1/embeddings	支持使用单独的 Gemini Embedding 模型别名，例如 gemini-embedding-2。
/v1/responses	通过基于 Chat 的 Responses 桥接提供支持，而不会调用 Google 原生 Interactions API。没有对应 Chat 语义的字段会被忽略。
/v1/messages	通过转换到 Chat Completions 提供支持。/v1/messages/count_tokens 不可用，因为它要求使用 Anthropic 支持的模型。
/v1/completions	不受 Google 兼容 API 支持；该 API 记录的是 Chat Completions，而不是旧版提示词补全路由。
/v1/audio/*	不支持。请通过 Chat Completions 发送受支持的音频输入；Gemini 语音生成和 Live API 使用不同的原生 API。
/v1/images/generations	拒绝，因为标准化 AISIX 路由要求 provider: openai，即使 Google 提供 OpenAI 兼容图像路由也不例外。请通过 /passthrough/google/images/generations 发送当前 Google 图像模型 ID。
/v1/videos	拒绝，因为 google 不在标准化视频路由的服务提供方允许列表中。请通过 /passthrough/google/videos 提交 Google OpenAI 兼容视频任务，并通过 /passthrough/google/videos/<id> 轮询。
/v1/rerank	不支持。AISIX 路由的服务提供方允许列表不包含 google，Google 也未在此处提供匹配的 Rerank 路由。
/v1/files、/v1/batches	无法构成端到端 AISIX 工作流。Google 支持 OpenAI 兼容的批处理创建和状态查询，但文件上传和下载需要使用此目录路由之外的原生 API。
/passthrough/google/*	通过已配置的透传路由可用于 OpenAI 兼容 API Base 下的原始路由。

本页的 /passthrough/google 路径假定一条透传路由认领该前缀，target_url 设为目录 api_base 并挂上此服务提供方密钥；在调用方 API Key 的 allowed_routes 上授予路由名称。该目标以 /v1beta/openai 结尾，因此透传始终位于 Google OpenAI 兼容 API 区域内，无法访问 models/<model>:generateContent、models/<model>:streamGenerateContent、interactions、原生文件操作或 Live API 等同级原生路由。这些原生 API 还使用不同的请求形态和 API Key 请求头，因此不要在此目录服务提供方密钥后构造原生 Gemini 路径。

透传会转发请求和响应正文，但不会重写 AISIX 模型别名，因此请发送准确的 Google 模型 ID。哪些请求形态会记录 Token 用量，参见信封识别与用量。透传流量记录的 Token 不会推进 tpm 或 tpd 计数器、确定模型成本，也不会增加预算支出；调用方 Key 的请求次数限制仍适用于每次调用。请参阅透传路由。

后续步骤

现在，你已通过 Google AI Studio 将 AISIX 连接到 Gemini，并验证了模型别名。接下来可阅读以下指南：

• 模型别名：为此别名配置路由、重试行为或成本元数据。
• Google Vertex AI：改为通过 Google Cloud 路由 Gemini。
• 服务提供方特定覆盖项：当上游 API 与其适配器不同时，调整请求和响应形态。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特定边界。