Google GenAI SDK for TypeScript¶
Your TypeScript keeps calling ai.models.generateContent(...). 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 on npm (GoogleGenAI), for Node.js and other runtimes. 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 (Node.js) | Constructor option | Value |
|---|---|---|---|
| Base address | GOOGLE_GEMINI_BASE_URL |
httpOptions: { baseUrl } |
https://<your-gateway> (no path: the SDK adds it) |
| API version | GOOGLE_GENAI_API_VERSION |
apiVersion |
v1beta |
| Key | GOOGLE_API_KEY (or GEMINI_API_KEY) |
apiKey |
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¶
import { GoogleGenAI } from '@google/genai';
const ai = new GoogleGenAI({
apiKey: 'vk_…',
apiVersion: 'v1beta',
httpOptions: { baseUrl: 'https://<your-gateway>' },
});
// or, in Node.js: new GoogleGenAI({}) with the three environment variables above
const response = await ai.models.generateContent({
model: 'gemini-3.5-flash',
contents: 'Say hello in Dutch.',
});
console.log(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¶
const stream = await ai.models.generateContentStream({
model: 'gemini-3.5-flash',
contents: 'Count to five.',
});
for await (const chunk of stream) {
process.stdout.write(chunk.text ?? '');
}
A stream from a GPT or Claude model arrives as Gemini chunks. Chats (ai.chats.create(...)) work the same way.
Tool calls¶
Function declarations work as documented by Google, on every provider: the model's calls come back as
functionCall parts, and you send results as functionResponse parts.
const response = await ai.models.generateContent({
model: 'claude-sonnet-4.5',
contents: 'Weather in Utrecht?',
config: {
tools: [{
functionDeclarations: [{
name: 'get_weather',
description: 'Weather for a city',
parametersJsonSchema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
}],
}],
},
});
console.log(response.functionCalls);
Reading what the gateway did¶
Version 1.6 and later keep the response headers on generateContent answers, streamed or not (1.12 and later on the
other calls too), in sdkHttpResponse.headers:
const response = await ai.models.generateContent({ model: 'gemini-3.5-flash', contents: 'Hi' });
const headers = response.sdkHttpResponse?.headers ?? {};
console.log(headers['x-vidai-request-id']); // quote this; paste it into Request logs › Request reference
console.log(headers['x-vidai-model']); // the model that answered
console.log(headers['x-vidai-adapted']); // what translation changed, if anything
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
throws its usual ApiError with status and message. That error doesn't carry the response headers, so the
gateway's stable x-vidai-error-code isn't in reach here: branch on status, and look the call up in
Request logs (filter Key and Model) when you need the exact reason.
| 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 |
import { ApiError } from '@google/genai';
try {
await ai.models.generateContent({ model: 'gemini-3.5-flash', contents: 'Hi' });
} catch (err) {
if (err instanceof ApiError) {
console.log(err.status, err.message);
} else {
throw err;
}
}
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. ai.models.list() returns exactly the models your key may call, and ai.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 |
|---|---|
generateContent, streaming, chats, function calling, images and PDFs |
Yes, to Gemini, Vertex AI, OpenAI, Azure OpenAI and Anthropic models |
ai.models.list(), ai.models.get() |
Yes: answered by the gateway, only the models your key may call |
Files (ai.files) |
Yes, to Gemini only; with the SDK, both steps of an upload go through the gateway |
Embeddings (embedContent) |
Yes, to Gemini only |
| Live API (WebSocket) | No |
Keep the client in Gemini API mode (no vertexai or enterprise option) 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. With a project and
location, the SDK signs calls with your Google Cloud credentials, which the gateway doesn't accept.
Check it works in a minute¶
node --input-type=module -e "import {GoogleGenAI} from '@google/genai'; const r = await new GoogleGenAI({}).models.generateContent({model:'gemini-3.5-flash', contents:'ping'}); console.log(r.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
httpOptions.retryOptions. 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
topK) is dropped or adjusted, never a failed call;x-vidai-adaptednames it. - In a browser, the key would be visible to every visitor. Call the gateway from a server, as you would with a provider's key.