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: 0on the call if you don't want both. - The gateway's own 429 has no
Retry-Afterheader; back off on your side. ANTHROPIC_BASE_URLmeans something different here: the AI SDK expects it with/v1, the Anthropic SDK without. Don't share one variable between them.- Prefer the
baseURLoption to the environment variables when one process uses several SDKs, so each gets the address it expects.