Gateway: Gemini SDK

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, also under /agents/{agent_id}/v1 and /openai/agents/{agent_id}/v1 with the agent ID in the path. 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. For OpenAI-compatible clients that allow only one extra header, such as n8n, put the agent ID in the URL instead: https://gateway.traccia.ai/agents/<agent-id>/v1. If both are set, the header wins.

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.