Skip to content

AI SDK by Vercel

Your TypeScript keeps calling generateText and streamText. Point the provider at the gateway and every call is governed: it's checked against your policies, charged to the right team and recorded in Request logs. Because the gateway translates between formats, one provider set up once can reach OpenAI, Claude and Gemini models.

What it is

The ai package and its provider packages (@ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google). Each provider speaks its own company's request format, and each takes a baseURL and an apiKey. Any of them works with the gateway; the OpenAI one with .chat(...) is the simplest, as it reaches every provider through Chat Completions.

The two settings

Provider package Base address (baseURL) Key (apiKey) Sends the key as
@ai-sdk/openai (createOpenAI) https://<your-gateway>/v1 Your Vidai key (starts vk_) Authorization: Bearer
@ai-sdk/anthropic (createAnthropic) https://<your-gateway>/v1 (with /v1: this provider adds only /messages) Your Vidai key x-api-key
@ai-sdk/google (createGoogleGenerativeAI) https://<your-gateway>/v1beta Your Vidai key x-goog-api-key

Each provider also reads environment variables: OPENAI_BASE_URL and OPENAI_API_KEY; ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY; GOOGLE_GENERATIVE_AI_API_KEY (the Google provider has no variable for the address, so pass baseURL). Never use a provider's own key: the gateway holds those.

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.

A minimal call

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';

const vidai = createOpenAI({
  baseURL: 'https://<your-gateway>/v1',
  apiKey: process.env.VIDAI_API_KEY, // vk_…
});

const { text } = await generateText({
  model: vidai.chat('gpt-4o-mini'),
  prompt: 'Say hello in Dutch.',
});
console.log(text);

Use vidai.chat(...), not vidai(...): the plain call uses OpenAI's Responses API, which the gateway passes only to OpenAI and Azure OpenAI models. With .chat, the same code calls Claude or Gemini: put a name such as claude-sonnet-4.5 in it and the gateway translates the request and the answer.

The other two providers, set up the same way:

import { createAnthropic } from '@ai-sdk/anthropic';
import { createGoogleGenerativeAI } from '@ai-sdk/google';

const viaMessages = createAnthropic({ baseURL: 'https://<your-gateway>/v1', apiKey: process.env.VIDAI_API_KEY });
const viaGemini = createGoogleGenerativeAI({ baseURL: 'https://<your-gateway>/v1beta', apiKey: process.env.VIDAI_API_KEY });

await generateText({ model: viaMessages('claude-sonnet-4.5'), prompt: 'Hi' });
await generateText({ model: viaGemini('gemini-3.5-flash'), prompt: 'Hi' });

These reach other providers' models too (viaMessages('gpt-4.1') works), with the limits of each format's translation.

Streaming

import { streamText } from 'ai';

const result = streamText({
  model: vidai.chat('claude-sonnet-4.5'),
  prompt: 'Count to five.',
});
for await (const part of result.textStream) {
  process.stdout.write(part);
}

A stream from any provider arrives in the format the provider package expects, so streamText, useChat and the other UI helpers work unchanged.

Tool calls

Tools defined with tool(...) work on every provider the gateway translates to:

import { generateText, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: vidai.chat('gemini-3.5-flash'),
  prompt: 'Weather in Utrecht?',
  tools: {
    getWeather: tool({
      description: 'Weather for a city',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, forecast: 'sunny' }),
    }),
  },
});
console.log(result.toolCalls);

To let the model answer after the tool has run, set a stop condition (stopWhen) as the AI SDK documentation shows for your version.

Reading what the gateway did

response.headers on the result holds the headers the gateway adds:

const { text, response } = await generateText({ model: vidai.chat('gpt-4o-mini'), prompt: 'Hi' });
console.log(response.headers?.['x-vidai-request-id']); // quote this; paste it into Request logs › Request reference
console.log(response.headers?.['x-vidai-model']);      // the model that answered
console.log(response.headers?.['x-vidai-adapted']);    // what translation changed, if anything

With streamText, read them from await result.response.

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 format of the provider package you use, and the AI SDK throws an APICallError with statusCode and responseHeaders. Match on x-vidai-error-code rather than the message: codes are stable.

Status Common gateway codes
400 bad_request, provider_override_not_allowed, an endpoint this provider doesn't serve
401 missing_api_key, invalid_api_key, conflicting_auth_headers
403 api_key_disabled, model_not_allowed, denied_by_routing_rule, content_guardrail_blocked
404 model_not_found, endpoint_not_found
413 payload_too_large
429 rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded
5xx ai_traffic_suspended, fallback_exhausted, upstream_timeout, upstream_unreachable
import { APICallError } from 'ai';

try {
  await generateText({ model: vidai.chat('gpt-4o-mini'), prompt: 'Hi', maxRetries: 0 });
} catch (err) {
  if (APICallError.isInstance(err)) {
    console.log(err.statusCode, err.responseHeaders?.['x-vidai-error-code']);
    console.log(err.responseHeaders?.['x-vidai-request-id']);
  } else {
    throw err;
  }
}

After retries, the AI SDK wraps the last error in a RetryError; its lastError is the APICallError.

Model names

Send the names your organisation has approved, as listed under Models in the Control room. A call to GET https://<your-gateway>/v1/models with your key lists exactly the models it may call. 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
generateText, streamText, generateObject, tools, images, through .chat(...), @ai-sdk/anthropic or @ai-sdk/google Yes, to OpenAI, Azure OpenAI, Anthropic, Gemini and Vertex AI models
The OpenAI provider's default (vidai('…') or .responses(…)) Yes, to OpenAI and Azure OpenAI only; another provider gets a clear 400
Embeddings, images, speech and transcription (@ai-sdk/openai) Yes, to OpenAI and Azure OpenAI only
Provider-specific tools (Anthropic bash, textEditor; OpenAI's Responses tools) Only on that provider's own models

Check it works in a minute

VIDAI_API_KEY="vk_…" node --input-type=module -e "import {createOpenAI} from '@ai-sdk/openai'; import {generateText} from 'ai'; const v = createOpenAI({baseURL:'https://<your-gateway>/v1', apiKey:process.env.VIDAI_API_KEY}); console.log((await generateText({model:v.chat('gpt-4o-mini'), prompt:'ping', maxOutputTokens:5})).text)"

A short answer means the address and key are right. The call shows in Request logs within seconds.

Good to know

  • The AI SDK retries twice by default. A fallback chain may already have tried another model before you see an error; set maxRetries: 0 on the call if you don't want both.
  • The gateway's own 429 has no Retry-After header; back off on your side.
  • ANTHROPIC_BASE_URL means something different here: the AI SDK expects it with /v1, the Anthropic SDK without. Don't share one variable between them.
  • Prefer the baseURL option to the environment variables when one process uses several SDKs, so each gets the address it expects.