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-Afterheader; 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-adaptednames it. - Never put the key in the address (
?key=): the gateway accepts it only in a header, which is where the SDK sends it.