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，且末尾不带斜杠
# 本地 On-Premises 快速入门使用 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 会从目录服务提供方推导适配器；adapter 字段仅接受用于 BYO 服务提供方密钥。

❷ 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：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 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，而不是旧版 Prompt 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 下的原始路由。

目录 api_base 以 /v1beta/openai 结尾，因此透传始终位于 Google OpenAI 兼容 API 区域内，无法访问 models/<model>:generateContent、models/<model>:streamGenerateContent、interactions、原生文件操作或 Live API 等同级原生路由。这些原生 API 还使用不同的请求形态和 API Key 请求头，因此不要在此目录服务提供方密钥后构造原生 Gemini 路径。

透传会转发请求和响应正文，但不会重写 AISIX 模型别名。请发送准确的 Google 模型 ID，并确保调用方 API Key 能访问至少一个服务提供方为 google 的已配置模型。AISIX 对透传请求记录零输入和输出 Token，因此基于 Token 的预算和成本计算不包含图像、视频或其他透传流量；请求次数限制仍然适用。请参阅服务提供方透传。

后续步骤

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

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

准备工作​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

使用 Gemini 思考和工具​

查看端点支持情况​

后续步骤​