AI Gateway
AI SDK with AI Gateway
Install the ai package:
AI SDK
See the AI SDK getting-started guide for runtime and package setup.
npm
See the generateText reference for options and return values.
pnpm
npm installai@latest
bun
Generate text by passing a plain string model ID. AI Gateway resolves the provider and routes the request automatically.
import { generateText } from'ai';
const { text } =awaitgenerateText({
model:'anthropic/claude-sonnet-5',
prompt:'Explain quantum computing in one paragraph.',
});
console.log(text);
Streaming
See the streamText reference for stream events and response helpers.
Stream responses token-by-token for real-time output:
});
constresult=streamText({
model:'openai/gpt-6-astra',
import { streamText } from'ai';
prompt:'Write a short story about a robot discovering music.',
process.stdout.write(textPart);
See the AI SDK structured-output guide for schemas, output types, and validation.
forawait (consttextPartofresult.textStream) {
Generate type-safe structured data with generateText and Output.object and a Zod schema:
name:z.string(),
import { z } from'zod';
import { generateText, Output } from'ai';
model:'anthropic/claude-sonnet-5',
output:Output.object({ schema:z.object({
}) }),
});
age:z.number(),
prompt:'Extract: John is 30 years old and lives in NYC.',
const { output } =awaitgenerateText({
console.log(output); // { name: 'John', age: 30, city: 'NYC' }
Tool calling
See the AI SDK tool-calling guide for execution, tool results, and multi-step calls.
Define tools that models can invoke to interact with external systems. Describe each tool's input with inputSchema:
import { generateText, isStepCount, tool } from'ai';
tools: {
location:z.string().describe('City name, e.g. San Francisco'),
import { z } from'zod';
},
model:'anthropic/claude-sonnet-5',
location,
}),
description:'Get the current weather for a location',
stopWhen:isStepCount(5),
execute:async ({ location }) => ({
getWeather:tool({
inputSchema:z.object({
}),
}),
});
temperature:72,
condition:'sunny',
console.log(text);
Reasoning
stopWhen is what lets the model answer in words. Without it the request stops as soon as the tool runs, finishing with finishReason: 'tool-calls' and an empty text. The toolResults field contains the tool result, but the model has not generated a text response from it.
See the AI SDK reasoning guide for reading reasoning output and configuring supported models.
Reasoning models think before answering. On AI SDK 7, set the top-level reasoning option and the SDK translates it to each provider's native API, so the same code works across Anthropic, OpenAI, and Google:
import { generateText } from'ai';
constresult=awaitgenerateText({
model:'anthropic/claude-sonnet-5',
});
reasoning:'high',
console.log(result.reasoningText);
console.log(result.text);
reasoning option is silently ignored: the
request succeeds, but no thinking happens and
reasoningText is empty. There
is no error to catch. Use
providerOptions on 6, or upgrade to 7.
For per-provider configuration and the full effort-level reference, see Reasoning.
See Inputs & Tools for complete vision, PDF, audio, and video examples across API formats.
Images and file input
See the AI SDK file-part guide for bytes, data URLs, remote URLs, and media types.
Swap a message's plain string content for an array of parts. A file part carries the bytes and a mediaType telling the model how to read them, so the same shape covers images and documents:
{ type:'text', text:'Describe this image in one sentence.' },
model:'anthropic/claude-opus-5',
{
import { generateText } from'ai';
],
data:fs.readFileSync('./diagram.png'),
},
{
const { text } =awaitgenerateText({
import fs from'node:fs';
role:'user',
content: [
mediaType:'image/png',
},
],
});
console.log(text);
type:'file',
messages: [
data takes a Buffer, a Uint8Array, a base64 string, or a URL. Point mediaType at the document type to send a PDF instead:
({
type:'file',
data:fs.readFileSync('./report.pdf'),
mediaType:'application/pdf',
});
{ type: 'image', image } part. That part still works
but is deprecated in AI SDK 7, which warns at runtime and asks for a
file
part with an
image/* media type. The
file form shown above works on both
7 and 6.
Whether a given model accepts images or PDFs is a per-model question. Check the model list before sending an attachment.
Version compatibility
The examples on this page use AI SDK 7, except tabs explicitly labeled AI SDK 6. AI Gateway supports both versions, but some client APIs differ:
Feature
System instructions
Image generation
Tool-loop stop condition
instructions
AI SDK 6
onEnd, onStepEnd
telemetry
Completion callbacks
generateImage or its experimental alias
Not supported
isStepCount
Supported
result.fullStream
Top-level reasoning
Full event stream
AI SDK 7
result.stream
generateImage
stepCountIs
AI SDK 7 requires Node.js 22 or later and ESM. Check your installed version with pnpm list ai. See the AI SDK 7 migration guide before upgrading. The AI SDK for Python beta uses a separate package and API.
Authentication
See the AI SDK AI Gateway provider reference for API keys, OIDC, and custom provider instances.
The AI SDK uses the AI_GATEWAY_API_KEY environment variable by default. Set it in your .env.local file:
AI_GATEWAY_API_KEY=your_ai_gateway_api_key
On Vercel deployments, you can also authenticate with OIDC tokens for keyless authentication.
See Authentication for more details.
Build with a template
Start with an AI SDK template to build a chatbot or route form submissions with Jev:
Next steps
Last updated September 14, 2026
Cross-link map: AI SDK with AI Gateway (/docs/ai-gateway/sdks-and-apis/ai-sdk)From the Vercel docs graph (built 2026-09-21T05:26:59.511Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.jsonSemantically closest pagesAI SDK for Python with AI Gateway — Build AI-powered Python applications using the AI SDK for Python with AI Gateway for unified access to 200+ models.AI SDK — Build TypeScript agents and AI applications with a unified API for models, tools, structured output, and streaming.AI Gateway SDKs and APIs — Connect to AI Gateway with the AI SDK, Python, REST, or compatible OpenAI, Anthropic Messages, OpenResponses, and CoherePython with AI Gateway: OpenAI and Anthropic SDKs — Use AI Gateway with Python through OpenAI or Anthropic SDKs with full streaming, tool calling, and async support.AI Gateway Model Modalities — The inputs and outputs AI Gateway models work with: text, image, and video generation, speech to text, text to speech, rThis page links to (20)Generating Structured DataReasoningTool CallingPromptsGetting StartedMigrate AI SDK 6.x to 7.0generateTextstreamTextAI GatewayAI Gateway Authentication and BYOK — Authenticate AI Gateway requests with API keys or OIDC tokens, and configure bring your own key \(BYOK\) credentials forAI Gateway OIDC Authentication — Authenticate AI Gateway requests from Vercel deployments with OIDC tokens. Configure the AI SDK or send bearer tokens diAI Gateway Inputs and Tools — Send images, PDFs, audio, and video to AI Gateway models, and connect models to application functions with tool use.AI Gateway Provider Routing and Fallbacks — Configure provider routing, ordering, and fallback behavior in Vercel AI Gateway.AI Gateway Reasoning — Discover model reasoning capabilities and configure effort across AI SDK, Chat Completions, Messages, and Responses withAI SDK for Python with AI Gateway — Build AI-powered Python applications using the AI SDK for Python with AI Gateway for unified access to 200+ models.Anthropic Messages API with AI Gateway — Use the Anthropic Messages API with AI Gateway. Configure authentication and send requests with streaming, tools, imagesOpenAI Chat Completions API with AI Gateway — Use OpenAI SDKs with the AI Gateway Chat Completions API. Configure the base URL and authentication for chat, streaming,OpenResponses API with AI Gateway — Use the OpenResponses API specification with AI Gateway for a unified, provider-agnostic interface.OpenAI Responses API with AI Gateway — Use the OpenAI Responses API with AI Gateway to generate text, call tools, stream tokens, and more across any supportedBuild AI agents with AI Gateway and AI SDK — Build AI agents on Vercel with AI Gateway and AI SDK, then make them reliable, capable, and durable with Sandbox, Chat SPages that link here (14)By site: vercel-docs (14)Vercel AI Gateway: Models, Routing, and Observability — Call AI models from any infrastructure through a managed gateway. Centralize credentials, request logs, spend budgets, rAI Gateway FAQ — Answers to common questions about AI Gateway, including request errors, pricing and markup, SDK and API compatibility, mMigrate to AI Gateway Using Your Coding Agent — Move your app's model calls to Vercel AI Gateway with a single coding-agent prompt, whatever provider or SDK you use todAI Gateway Text Generation Quickstart — Generate and stream text responses using AI Gateway.AI Gateway Audio Input — Analyze recorded audio with AI Gateway, compare audio input with transcription and realtime voice, and choose a supporteAI Gateway File and PDF Input — Send PDFs and documents to AI Gateway models with examples for each supported SDK and API format.AI Gateway Tool Use and Function Calling — Connect AI Gateway models to application tools with AI SDK 7, Python, Chat Completions, Messages, and Responses examplesAI Gateway Video Input — Analyze video clips with AI Gateway using AI SDK 7, Python, Chat Completions, and Responses / OpenResponses.AI Gateway Vision and Image Input — Analyze images with AI Gateway using AI SDK 7, the Python beta, Chat Completions, Messages, and Responses APIs.AI Gateway SDKs and APIs — Connect to AI Gateway with the AI SDK, Python, REST, or compatible OpenAI, Anthropic Messages, OpenResponses, and CohereAI SDK for Python with AI Gateway — Build AI-powered Python applications using the AI SDK for Python with AI Gateway for unified access to 200+ models.Cohere Rerank API with AI Gateway — Use the Cohere-compatible Rerank API with AI Gateway to reorder documents by relevance with the Cohere SDK or plain HTTPAI Gateway REST API Reference — Reference for AI Gateway REST endpoints: models, usage, generations, and reporting.AI SDK with MCP — Connect the AI SDK to an MCP server on Vercel, discover its tools, and call them with models served through AI Gateway.
Was this helpful?
