Gemini provider

You can proxy requests to Gemini AI models through AI Gateway by creating AI Model Provider and AI Model entities. This reference documents all supported AI capabilities, configuration requirements, and provider-specific details needed for proper integration.

AI Gateway supports both Gemini Standard and Gemini Enterprise. The following sections cover both variants together and note where their capabilities differ.

AI Gateway automatically routes requests to the appropriate Gemini API endpoints. The following table shows the upstream paths used for each capability.

The following tables show the AI capabilities supported by the Gemini provider when configuring AI Models.

By default, AI Gateway uses the path templates shown in the tables below (e.g., /chat/completions, /embeddings, etc.). To customize these paths, configure the config.paths field in your AI Model entity. Custom paths take the form {configured_path}/{template_path} — for example, if you set a custom path of /v2, requests to /embeddings would be routed to /v2/embeddings.

Text generation

Support for Gemini text generation capabilities:

Embeddings

Support for Gemini embeddings generation:

Image

Support for Gemini image generation and editing capabilities:

For requests with large payloads, consider increasing config.max_request_body_size on your AI Model entity to three times the raw binary size.

Supported image sizes and formats vary by model. Refer to your provider’s documentation for allowed dimensions and requirements.

Video

Support for Gemini video generation capabilities:

For requests with large payloads (video generation), consider increasing config.max_request_body_size on your AI Model entity to three times the raw binary size.

Realtime

Support for Gemini’s bidirectional streaming for realtime applications:

Realtime processing uses WebSocket protocol (ws/wss). This protocol is automatically enabled when you configure your AI Model with the realtime capability.

¹ Gemini Standard: Realtime processing for Gemini is supported in the native format from SDK only

Batches

Support for Gemini batch processing capabilities:

² Gemini Standard: Batches processing for Gemini is supported in the native format from SDK only

Batch jobs run on an AI Model with type: "api". Regular models handle synchronous capabilities like generate and embeddings, so a model that serves batches can’t serve those capabilities.

Files

Support for Gemini file management capabilities:

³ Gemini Standard: Files processing for Gemini is supported in the native format from SDK only ⁴ Gemini Enterprise: Gemini Enterprise does not have a dedicated Files API. File storage uses Google Cloud Storage, similar to Amazon S3.

Files are managed through an AI Model with type: "api", the same type that serves batches. Create one dedicated AI Model for batches and files, and keep generate and embeddings on a separate regular model, because each model is either a regular model or an API model, not both.

By default, AI Gateway routes Gemini requests to Gemini Standard at https://generativelanguage.googleapis.com.

To route requests to Gemini Enterprise, set config.gcp_environment (with api_endpoint, location_id, and project_id) on the AI Model’s target; see Select Gemini Standard or Gemini Enterprise. AI Gateway then sends them to https://aiplatform.googleapis.com/.

You don’t need to set the URL yourself. You only need to set upstream_url in your AI Model configuration if you’re using a self-hosted or Gemini-compatible endpoint instead.

By default, AI Gateway uses OpenAI-compatible request formats. Configure a native format in your AI Model to use Gemini-specific APIs and features.

The following native Gemini formats are supported:

Provider-specific limitations for native formats

Gemini Standard:

• Gemini only supports auth.allow_override = false.

Gemini Enterprise:

• None.

To use Gemini with AI Gateway, configure a new AI Model Provider. You can then access supported AI Models from Gemini.

Gemini Standard

Here’s a minimal configuration for chat completions, authenticating with an API key:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/model-providers \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "Gemini Production",
      "name": "my-gemini-account",
      "type": "gemini",
      "config": {
        "auth": {
          "type": "basic",
          "headers": [
            {
              "name": "x-goog-api-key",
              "value": "'$GEMINI_API_KEY'"
            }
          ]
        }
      }
    }
    '

ai_gateway_model_providers:
  - ref: my-gemini-account
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Gemini Production
    name: my-gemini-account
    type: gemini
    config:
      auth:
        type: basic
        headers:
        - name: x-goog-api-key
          value: !secret {source: !env GEMINI_API_KEY}

Gemini Enterprise

Gemini Enterprise requires GCP credentials instead of an API key. The AI Model Provider only handles authentication. auth.type: gcp by itself doesn’t select Gemini Enterprise, since Gemini Standard can use the same GCP auth. What routes to Gemini Enterprise is config.gcp_environment on the target of the AI Model that attaches to this provider. See Select Gemini Standard or Gemini Enterprise.

Create the provider to store your GCP credentials:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/model-providers \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "Gemini Enterprise Production",
      "name": "my-gemini-enterprise-account",
      "type": "gemini",
      "config": {
        "auth": {
          "type": "gcp",
          "use_gcp_service_account": true,
          "service_account_json": "'$GCP_ACCOUNT_JSON'"
        }
      }
    }
    '

ai_gateway_model_providers:
  - ref: my-gemini-enterprise-account
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Gemini Enterprise Production
    name: my-gemini-enterprise-account
    type: gemini
    config:
      auth:
        type: gcp
        use_gcp_service_account: true
        service_account_json: !secret {source: !env GCP_ACCOUNT_JSON}

Then attach an AI Model to it, setting config.gcp_environment on the target to route to Gemini Enterprise:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/models \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "my-gemini-enterprise-model",
      "display_name": "my-gemini-enterprise-model",
      "type": "model",
      "capabilities": [
        "generate"
      ],
      "formats": [
        {
          "type": "openai"
        }
      ],
      "config": {
        "route": {
          "paths": [
            "/v1"
          ]
        }
      },
      "targets": [
        {
          "name": "gemini-3.5-flash",
          "provider": "my-gemini-enterprise-account",
          "config": {
            "type": "gemini",
            "gcp_environment": {
              "api_endpoint": "aiplatform.googleapis.com",
              "location_id": "global",
              "project_id": "my-gcp-project-id"
            }
          }
        }
      ],
      "policies": []
    }
    '

ai_gateway_models:
  - ref: my-gemini-enterprise-model
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    name: my-gemini-enterprise-model
    display_name: my-gemini-enterprise-model
    type: model
    capabilities:
    - generate
    formats:
    - type: openai
    config:
      route:
        paths:
        - "/v1"
    targets:
    - name: gemini-3.5-flash
      provider: my-gemini-enterprise-account
      config:
        type: gemini
        gcp_environment:
          api_endpoint: aiplatform.googleapis.com
          location_id: global
          project_id: my-gcp-project-id
    policies: []

targets[].config.gcp_environment requires api_endpoint, location_id, and project_id. Set api_endpoint to the hostname for your location: aiplatform.googleapis.com for global, {location_id}-aiplatform.googleapis.com for a single region such as us-east5, or aiplatform.{location_id}.rep.googleapis.com for the multi-region locations us and eu. You can also set it to a Private Service Connect endpoint.

Gemini Standard and Gemini Enterprise use the same gemini provider type. AI Gateway routes to Gemini Enterprise only when the AI Model target sets config.gcp_environment with api_endpoint, location_id, and project_id. Otherwise, it routes to Gemini Standard, whatever the credential type.

For clients that send native Gemini requests, the request path must match the variant:

• If the target sets gcp_environment, send Gemini Enterprise paths, such as /v1/projects/{project_id}/locations/{location}/publishers/google/models/{model_name}:generateContent.
• If the target doesn’t set gcp_environment, send Gemini Standard paths.

AI Gateway doesn’t rewrite the path from one variant to the other.

Gemini Enterprise requires credentials from Google Cloud Platform (GCP). Gemini Standard can also use GCP credentials instead of an API key by setting auth to gcp.

The authentication chain follows the same order of precedence as the gcloud tool:

1. Service account JSON defined directly in the provider: auth.service_account_json.
2. Service account JSON defined in environment variable GCP_SERVICE_ACCOUNT.
3. Workload IAM role (for example, a GKE or deployment service account).
4. IAM role attached to the VM instance.

For restricted networks, override the default endpoints with auth.metadata_url or auth.oauth_token_url.

Instead of a static service account key, you can configure the GCP provider to obtain temporary GCP credentials through Workload Identity Federation, exchanging credentials from an external identity provider for short-lived GCP tokens. This applies to both Gemini Standard and Gemini Enterprise, since both authenticate through the same GCP Provider auth.

To use Workload Identity Federation, set auth.type to gcp and add a workload_identity_federation object:

• source (required): The identity provider used to obtain temporary GCP credentials. Only aws_iam is supported.
• auth_json (optional): JSON configuration for the Workload Identity Federation token exchange, Google’s external_account credential config (audience, token URL, credential source, and optional service account impersonation URL). If not set, Kong falls back to the file path in the GOOGLE_APPLICATION_CREDENTIALS environment variable.

When source is aws_iam, provide AWS IAM credentials under aws to identify the AWS principal used in the token exchange, or omit them to fall back to the default AWS credentials provider chain (EC2 instance profiles, environment variables, and so on):

Here’s a configuration that authenticates with GCP by assuming an AWS IAM role:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/model-providers \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "Gemini Production",
      "name": "my-gemini-account",
      "type": "gemini",
      "config": {
        "auth": {
          "type": "gcp",
          "workload_identity_federation": {
            "source": "aws_iam",
            "aws": {
              "type": "aws",
              "assume_role_arn": "'$AWS_ASSUME_ROLE_ARN'",
              "role_session_name": "kong-gemini-wif"
            }
          }
        }
      }
    }
    '

ai_gateway_model_providers:
  - ref: my-gemini-account
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Gemini Production
    name: my-gemini-account
    type: gemini
    config:
      auth:
        type: gcp
        workload_identity_federation:
          source: aws_iam
          aws:
            type: aws
            assume_role_arn: !env AWS_ASSUME_ROLE_ARN
            role_session_name: kong-gemini-wif

A thought signature is an opaque thoughtSignature value that Gemini thinking models attach to response parts. Gemini uses the signature on the matching part of the next request to keep reasoning context across multi-turn conversations and function calls.

When an AI Model uses the openai format with a Gemini target, AI Gateway doesn’t return thoughtSignature in the OpenAI-compatible response, for streaming or non-streaming requests. When it translates assistant tool calls in the conversation history to Gemini, AI Gateway sets a placeholder signature on them so that Gemini accepts the history.

To receive the real thoughtSignature, use the native Gemini format, which returns Gemini’s response without translating it.

AI Gateway forwards requests for the Gemini Interactions API to Gemini without translating the request or response body. AI Gateway authenticates to Gemini with the credentials in the AI Model Provider.

To use the Interactions API, create an AI Model with the passthrough format and a Gemini target:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/models \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "my-gemini-interactions",
      "display_name": "my-gemini-interactions",
      "type": "model",
      "capabilities": [
        "generate"
      ],
      "formats": [
        {
          "type": "passthrough"
        }
      ],
      "config": {
        "route": {
          "paths": [
            "/gemini"
          ]
        }
      },
      "targets": [
        {
          "name": "gemini-2.5-flash",
          "provider": "my-gemini-account",
          "config": {
            "type": "gemini"
          }
        }
      ],
      "policies": []
    }
    '

ai_gateway_models:
  - ref: my-gemini-interactions
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    name: my-gemini-interactions
    display_name: my-gemini-interactions
    type: model
    capabilities:
    - generate
    formats:
    - type: passthrough
    config:
      route:
        paths:
        - "/gemini"
    targets:
    - name: gemini-2.5-flash
      provider: my-gemini-account
      config:
        type: gemini
    policies: []

Then send requests to the Interactions path through the AI Model’s route. For Gemini Standard, the path is /v1beta/interactions:

curl -X POST http://localhost:8000/gemini/v1beta/interactions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "input": "Say hello"
  }'

The same route also forwards streaming requests ("stream": true, relayed as server-sent events), background runs ("background": true), GET /gemini/v1beta/interactions/{id}, POST /gemini/v1beta/interactions/{id}/cancel, and DELETE /gemini/v1beta/interactions/{id}.

For Gemini Enterprise, the target must set config.gcp_environment, and the path is /v1beta1/projects/{project_id}/locations/{location}/interactions. Gemini Enterprise supports the Interactions API only in the global, us, and eu regions.

AI Gateway supports the Interactions API only in the native Gemini format. It doesn’t translate OpenAI Responses requests to Interactions, or Interactions requests to the OpenAI or Anthropic formats.