Skip to content

Google GenAI SDK for Python

Your Python code keeps calling client.models.generate_content(...). Point the client at the gateway and every call is governed: it's checked against your policies, charged to the right team and recorded in Request logs. The gateway translates both ways, so the same Gemini code can call GPT or Claude models and read the answer in the Gemini shape.

What it is

The official google-genai package for Python (from google import genai). It speaks the Gemini API format, which the gateway accepts at /v1beta/models/{model}:generateContent. It sends the key in the x-goog-api-key header.

The settings

Setting Environment variable In code Value
Base address GOOGLE_GEMINI_BASE_URL http_options=types.HttpOptions(base_url=...) https://<your-gateway> (no path: the SDK adds it)
API version GOOGLE_GENAI_API_VERSION http_options=types.HttpOptions(api_version=...) v1beta
Key GOOGLE_API_KEY (or GEMINI_API_KEY) api_key Your Vidai key (starts vk_), never a provider's key

Set the API version as well as the address. Version 3.0 of the SDK and later call /v1/... by default, and the gateway serves the Gemini format under /v1beta.

The gateway's address, and the base URL for each kind of SDK, are under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from Keys › Issue a key; its secret is shown once.

export GOOGLE_GEMINI_BASE_URL="https://<your-gateway>"
export GOOGLE_GENAI_API_VERSION="v1beta"
export GOOGLE_API_KEY="vk_…"

A minimal call

from google import genai
from google.genai import types

client = genai.Client(
    api_key="vk_…",
    http_options=types.HttpOptions(base_url="https://<your-gateway>", api_version="v1beta"),
)
# or: genai.Client() with the three environment variables above

response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="Say hello in Dutch.",
)
print(response.text)

The same code calls other providers' models: put a name such as gpt-4.1 or claude-sonnet-4.5 in model. The gateway translates the request for that provider and the answer back into the Gemini shape, streams and function calls included.

Streaming

for chunk in client.models.generate_content_stream(
    model="gemini-3.5-flash",
    contents="Count to five.",
):
    print(chunk.text or "", end="")

A stream from a GPT or Claude model arrives as Gemini chunks. Chats (client.chats.create(...)) and the async client (client.aio) work the same way.

Tool calls

Function declarations work as documented by Google, on every provider: the model's calls come back as function_call parts, and you send results as function_response parts.

weather = types.FunctionDeclaration(
    name="get_weather",
    description="Weather for a city",
    parameters={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
)
response = client.models.generate_content(
    model="claude-sonnet-4.5",
    contents="Weather in Utrecht?",
    config=types.GenerateContentConfig(
        tools=[types.Tool(function_declarations=[weather])],
        automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True),
    ),
)
print(response.function_calls)

Reading what the gateway did

Version 1.22 and later keep the response headers on every answer, streamed chunks included, in sdk_http_response.headers:

response = client.models.generate_content(model="gemini-3.5-flash", contents="Hi")
headers = response.sdk_http_response.headers
print(headers.get("x-vidai-request-id"))  # quote this; paste it into Request logs › Request reference
print(headers.get("x-vidai-model"))       # the model that answered
print(headers.get("x-vidai-adapted"))     # what translation changed, if anything

On an older version, upgrade, or look the call up in Request logs by Key and Model.

Other headers you may see: x-vidai-requested-model (when a different model answered), x-vidai-routing-rule, x-vidai-provider-key (the provider key's label, never its secret), x-vidai-fallback and x-vidai-fallback-from, x-vidai-fallback-attempts, x-vidai-translation-profile and x-vidai-pseudonymised. Cost is never in the answer: find the call in Request logs.

Errors

The gateway writes its errors in the Gemini format ({"error": {"code": …, "message": …, "status": …}}), so the SDK raises its usual ClientError (4xx) or ServerError (5xx). Match on the x-vidai-error-code header rather than the message: codes are stable.

Status Gemini status Common gateway codes
400 INVALID_ARGUMENT bad_request, provider_override_not_allowed, an endpoint this provider doesn't serve
401 UNAUTHENTICATED missing_api_key, invalid_api_key, conflicting_auth_headers
403 PERMISSION_DENIED api_key_disabled, model_not_allowed, denied_by_routing_rule, content_guardrail_blocked
404 NOT_FOUND model_not_found, endpoint_not_found
413 INVALID_ARGUMENT payload_too_large
429 RESOURCE_EXHAUSTED rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded
5xx UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL ai_traffic_suspended, fallback_exhausted, upstream_timeout, upstream_unreachable
from google.genai import errors

try:
    client.models.generate_content(model="gemini-3.5-flash", contents="Hi")
except errors.APIError as e:
    print(e.code, e.response.headers.get("x-vidai-error-code"))
    print(e.response.headers.get("x-vidai-request-id"))

A key that's switched off carries a short reason beside api_key_disabled in the error body (for example agent_suspended); treat the list of reasons as open-ended.

Model names

Send the names your organisation has approved, as listed under Models in the Control room; they needn't be Gemini models. client.models.list() returns exactly the models your key may call, and client.models.get(...) answers only for one of them. An alias set by an admin works like any other name; x-vidai-model says which model really answered.

What goes through the gateway

Feature Through the gateway
generate_content, streaming, chats, function calling, images and PDFs Yes, to Gemini, Vertex AI, OpenAI, Azure OpenAI and Anthropic models
client.models.list(), client.models.get() Yes: answered by the gateway, only the models your key may call
Files (client.files) Yes, to Gemini only; with the SDK, both steps of an upload go through the gateway
Embeddings (embed_content) Yes, to Gemini only
Live API (WebSocket) No

Vertex AI mode

Keep the client in Gemini API mode (vertexai unset) even when your models run on Vertex AI: the gateway decides where a call goes, and it reaches Vertex-hosted Gemini and Claude models for you. In Vertex AI mode (vertexai=True) with a project and location, the SDK signs every call with your Google Cloud credentials, which the gateway doesn't accept; switch to the settings above instead.

If your code must stay in Vertex AI mode, hand the SDK the Vidai key as its token, so it's sent as Authorization: Bearer:

from google.oauth2.credentials import Credentials

client = genai.Client(
    vertexai=True,
    project="your-project",
    location="europe-west4",
    credentials=Credentials(token="vk_…"),
    http_options=types.HttpOptions(base_url="https://<your-gateway>"),
)

To call Vertex AI's own paths over HTTP, see Vertex AI.

Check it works in a minute

python -c "from google import genai; print(genai.Client().models.generate_content(model='gemini-3.5-flash', contents='ping').text)"

With the three environment variables set, a short answer means the address, version and key are right. The call shows in Request logs within seconds.

Good to know

  • The SDK doesn't retry failed calls unless you set http_options.retry_options. A fallback chain may already have tried another model before you see an error, so you rarely need both.
  • The gateway's own 429 has no Retry-After header; back off on your side.
  • A parameter a GPT or Claude model can't take (for example top_k) is dropped or adjusted, never a failed call; x-vidai-adapted names it.
  • Never put the key in the address (?key=): the gateway accepts it only in a header, which is where the SDK sends it.