Gemini (Google AI Studio)

In this guide, you will connect AISIX AI Gateway to Google Gemini through the Google AI Studio OpenAI-compatible endpoint. Callers reach Gemini models through the gateway's OpenAI-compatible API, while AISIX owns the credential, model allowlist, rate limits, and usage accounting.

Google AI Studio exposes an OpenAI-compatible endpoint, so Gemini uses the openai adapter with a Google api_base. Use this configuration for Google AI Studio API keys. To route Gemini through Google Cloud instead, use the Google Vertex AI Upstream.

Prerequisites

Before starting, prepare the following:

A gateway with the admin API on :3001 and the proxy API on :3000.
The admin key from the gateway config.yaml.
A Google AI Studio API key from Google AI Studio. The OpenAI-compatible API root is https://generativelanguage.googleapis.com/v1beta/openai.

Supported Capabilities

Gemini is configured here as a chat-completions upstream through Google AI Studio's OpenAI-compatible mode.

Endpoint	Supported	Streaming	Notes
`/v1/chat/completions`	Yes	Yes	Primary path for `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`.
`/v1/images/generations`	No	—	Rejected: image generation requires `provider: "openai"`.
`/v1/rerank`	No	—	Gemini is not in the rerank allowlist (`openai`, `cohere`, `jina`).

See Provider Compatibility for the exact per-endpoint rules.

Configure the Gemini Upstream

Create a provider key, model alias, and caller API key for the Gemini-backed route.

Create a Provider Key

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export GEMINI_API_KEY="YOUR_PROVIDER_API_KEY"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/provider_keys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gemini-prod",
    "provider": "gemini",
    "adapter": "openai",
    "secret": "'"${GEMINI_API_KEY}"'",
    "api_base": "https://generativelanguage.googleapis.com/v1beta/openai"
  }'

❶ provider is gemini.

❷ adapter is openai, because Google AI Studio accepts OpenAI chat-completions requests.

❸ secret stores the Google AI Studio API key. It follows the credential-handling behavior in Provider Credentials.

❹ api_base is required. Use the root without a trailing slash; AISIX appends /chat/completions to it.

Copy the returned provider key ID.

Create a Model

export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gemini-flash-prod",
    "provider": "gemini",
    "model_name": "gemini-2.5-flash",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }'

❶ display_name is the alias callers send in model.

❷ model_name is the Gemini model ID, for example gemini-2.5-flash or gemini-2.5-pro.

❸ provider_key_id attaches the alias to the Gemini provider key.

Create a Caller API Key

Choose the caller API key value that the application will send to AISIX, then hash it for the admin resource:

export AISIX_API_KEY="YOUR_CALLER_API_KEY"

CALLER_KEY_HASH=$(printf '%s' "${AISIX_API_KEY}" | shasum -a 256 | awk '{print $1}')

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/apikeys" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${CALLER_KEY_HASH}"'",
    "allowed_models": ["gemini-flash-prod"]
  }'

❶ allowed_models must match the model alias you created.

Verify the Upstream

Send a chat-completions request through the AISIX proxy:

curl -sS -X POST "http://127.0.0.1:3000/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."}]
  }'

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias gemini-flash-prod. If AISIX returns an upstream authentication error, check the provider key secret; if it returns an upstream route error, check api_base and the Gemini model ID in model_name.

Behavior and Limits

This page covers Google AI Studio keys. For Gemini served through Google Cloud with a service account, use the native Google Vertex AI Upstream instead.

Response extensions beyond the OpenAI envelope are not normalized by default.

Next Steps

Model Aliases — add routing, cost metadata, and rate limits for this alias.
Google Vertex AI Upstream — route Gemini through Google Cloud instead.
Provider Compatibility — the endpoint-by-endpoint support rules.

Prerequisites​

Supported Capabilities​

Configure the Gemini Upstream​

Create a Provider Key​

Create a Model​

Create a Caller API Key​

Verify the Upstream​

Behavior and Limits​

Next Steps​