Gateway: Gemini SDK

Platform

Point the Gemini Developer API client at Traccia. Use http_options.base_url, not Vertex AI.

Use the Developer API client (google-genai / @google/genai), not Vertex AI. Set the HTTP base to https://gateway.traccia.ai/google. Python uses http_options.base_url and headers. TypeScript uses httpOptions.baseUrl (camelCase) and headers. Keep GEMINI_API_KEY on the client.

Vertex AI Is A Different Path

vertexai=True talks to Vertex URLs, not /google/v1beta/models/.... That is not this Gateway.

What this Gateway accepts

OpenAI: POST /openai/v1/chat/completions and GET /openai/v1/models. Anthropic: POST /anthropic/v1/messages. Gemini Developer API: POST /google/{v1beta|v1}/models/{model}:generateContent and :streamGenerateContent. Embeddings, the OpenAI Responses API, Assistants, Azure OpenAI paths, Vertex AI paths, and Anthropic Batches are not this Gateway. Those requests 404.

Headers

HeaderValue
X-Traccia-Api-KeyWorkspace key from Settings → API Keys
X-Traccia-Agent-IdSame Agent ID you would pass to init

Keep the provider API key on the client. The Gateway forwards it and does not store it. Missing Traccia key returns 401. Missing agent ID returns 400.

Client

python
import os
from google import genai
from google.genai import types


client = genai.Client(
    api_key=os.environ["GEMINI_API_KEY"],
    http_options=types.HttpOptions(
        base_url="https://gateway.traccia.ai/google",
        headers={
            "X-Traccia-Api-Key": os.environ["TRACCIA_API_KEY"],
            "X-Traccia-Agent-Id": "billing-bot",
        },
    ),
)


response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="hello",
)

The SDK joins this base with /v1beta/models/{model}:generateContent (or /v1/... if you set that API version). The request that must land is POST https://gateway.traccia.ai/google/v1beta/models/{model}:generateContent. Streaming uses :streamGenerateContent.

What Works

  • generate_content / generateContent
  • Streaming generate-content on v1beta or v1

Next Steps

Gateway Overview

What applies, headers, and what you see in traces.

Policies

Create Spend Cap or Model Boundary, then Activate Policy.

© 2026 Traccia.