Skip to main content
API7.ai Logo

Gemini (Google AI Studio)

Google Gemini is a family of multimodal models available through Google AI Studio and Google Cloud Vertex AI. This guide connects the Google AI Studio endpoint to AISIX so applications can call Gemini with gateway-managed credentials, access controls, rate limits, and usage accounting.

This guide uses the Google AI Studio endpoint. To route Gemini through Google Cloud instead, use Google Vertex AI.

Prerequisites​

Before starting, prepare the following:

  • One AISIX setup:
    • For AISIX Cloud, an environment with an attached gateway and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
    • For the open-source AISIX gateway, prepare either a local AISIX installation or the Docker setup from the Open-Source AISIX Gateway Quickstart. Configure the gateway to load a declarative resources file.
  • A Google AI Studio API key from Google AI Studio.
  • curl and jq.

Configure with AISIX Cloud​

Export the AISIX Cloud connection details:

# AISIX_CP is the Admin API base URL; include /api and omit a trailing slash
# The local On-Premises quickstart uses 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"

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

Because Google AI Studio provides an OpenAI-compatible endpoint, AISIX connects through the openai adapter and uses the Google AI Studio API root as api_base.

Create a Provider Key​

Create the provider key that stores the Google AI Studio credential and API root, and allow the environment to use it:

# Replace with your values
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 is google, the catalog provider ID for Google AI Studio. The AISIX Cloud Admin API derives the adapter from the catalog provider; the adapter field is only accepted on BYO provider keys.

❷ api_key stores the Google AI Studio API key. It follows the credential-handling behavior in Provider Keys.

❸ api_base is optional for this catalog provider, because the AISIX Cloud Admin API fills in this same value when you omit it. Set it explicitly so the upstream root stays visible on the resource. Use the root without a trailing slash; AISIX appends /chat/completions to it.

The command captures the returned provider key ID in PROVIDER_KEY_ID.

Create a Model​

Create the model alias callers will send in requests:

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 is the alias callers send in model.

❷ model_name is the Gemini model ID, for example gemini-3.6-flash. Use a stable ID from the Gemini models page and review its lifecycle before deploying it; Google retires older stable and preview IDs on published schedules.

❸ provider_key_id attaches the alias to the Gemini provider key.

Create a Caller API Key​

Create the caller API key resource that can access the model alias. The server generates the key value and returns the plaintext once in the response:

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}"

The allowed_models value references the model by its ID. Store the plaintext key securely; it is not retrievable later.

The new resources project to the attached gateway automatically.

Configure with the Open-Source AISIX Gateway​

Export the upstream credential and choose the caller API key that applications will send to the gateway:

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

Create a complete declarative resources file for this provider:

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"

If AISIX is installed locally, validate the file before loading it:

aisix validate --resources resources.yaml

After validation, start the gateway with the referenced environment variables in its process environment. Reload an existing gateway only if those variables are already available to the process; otherwise, restart it with the updated environment.

If you use Docker, adapt the validation and startup commands in the Open-Source AISIX Gateway Quickstart. Mount this resources.yaml file and pass every environment variable it references with -e in both commands. After the resources load, prepare the shared verification request below:

export AISIX_API_KEY="$CALLER_API_KEY"

Verify the Provider Connection​

Export the AISIX gateway origin:

# The local quickstarts use http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

Send a chat-completions request through the AISIX proxy:

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."
      }
    ]
  }'

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias gemini-flash-prod. If the request fails, check the provider key api_key, api_base, and the Gemini model ID in model_name.

Use Gemini Thinking and Tools​

Google's OpenAI-compatible chat endpoint accepts reasoning_effort. AISIX forwards this and other unmodeled top-level fields unchanged, so callers can use the levels supported by the selected Gemini model:

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

Gemini-specific controls under extra_body.google, such as thinking_config, also pass through. Do not send both reasoning_effort and Google's thinking-level or thinking-budget control in one request because they configure the same behavior. For gemini-3.6-flash and newer models, remove deprecated sampling fields such as temperature, top_p, and top_k; AISIX forwards them rather than removing them for you.

Gemini 3 tool calls carry a required thought signature at tool_calls[].extra_content.google.thought_signature. When continuing a function-calling turn on /v1/chat/completions, retain the complete assistant tool_calls objects and send them back unchanged with the tool results. AISIX preserves those raw objects, but it does not manage application conversation state.

Do not use the /v1/responses or translated /v1/messages routes for multi-step Gemini 3 tool loops. Those bridges reconstruct portable tool-call fields and do not replay Google's provider-specific thought signatures, so the next Gemini request can fail with a 400 validation error. See Thought signatures for OpenAI compatibility.

Review Endpoint Support​

The Google AI Studio OpenAI-compatible API has more routes than AISIX currently models for the google provider. Choose the route according to both layers:

RouteBehavior with a google provider key
/v1/chat/completionsSupported, including streaming and multimodal image, audio, or video inputs accepted by the selected model.
/v1/embeddingsSupported with a separate alias for a Gemini embedding model, such as gemini-embedding-2.
/v1/responsesSupported through the chat-based Responses bridge. It does not call Google's native Interactions API, and fields without a chat equivalent are ignored.
/v1/messagesSupported through translation to chat completions. /v1/messages/count_tokens is unavailable because it requires an Anthropic-backed model.
/v1/completionsNot supported by Google's compatibility API, which documents chat completions rather than the legacy prompt-completions route.
/v1/audio/*Not supported. Send supported audio input through chat completions; Gemini speech generation and the Live API use different native APIs.
/v1/images/generationsRejected because the normalized AISIX route requires provider: openai, even though Google publishes an OpenAI-compatible image route. Use /passthrough/google/images/generations with a current Google image model ID.
/v1/videosRejected because google is not in the normalized video route's provider allowlist. Use /passthrough/google/videos to submit and /passthrough/google/videos/<id> to poll Google's OpenAI-compatible video operations.
/v1/rerankNot supported. The AISIX route's provider allowlist excludes google, and Google does not publish a matching rerank route here.
/v1/files and /v1/batchesNot an end-to-end AISIX workflow. Google supports OpenAI-compatible batch creation and status, but file upload and download require its native API outside this catalog route.
/passthrough/google/*Supported for raw routes under the configured OpenAI-compatible API base.

The catalog api_base ends in /v1beta/openai, so passthrough stays inside Google's OpenAI-compatible API section. It cannot reach sibling native routes such as models/<model>:generateContent, models/<model>:streamGenerateContent, interactions, native file operations, or the Live API. Those native APIs also use a different request shape and API-key header, so do not construct native Gemini paths behind this catalog provider key.

Passthrough forwards request and response bodies without rewriting an AISIX model alias. Send the exact Google model ID, and ensure the caller API key can access at least one configured model whose provider is google. AISIX records passthrough requests with zero input and output tokens, so token-based budgets and cost calculations do not account for image, video, or other passthrough traffic. Request-count limits still apply. See Provider Passthrough.

Next Steps​

You have now connected AISIX to Gemini through Google AI Studio and verified the model alias. Continue with these guides: