Skip to content

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-After header; 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-adapted names 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.