AI Gateway Virtual Models for Reusable Model Configurations

A virtual model is a saved AI Gateway model configuration with its own model ID, vmc/<slug>. It pairs a model with the provider routing, fallbacks, regional inference, compliance settings, provider options, and observability tags its requests should use. Any client that takes a model name gets that configuration without sending the options itself, whether it's your own code, a chat platform, or a coding agent like Claude Code or Codex that can't pass AI Gateway options per request. Virtual models work with every model type in the catalog, and you can change their settings later without redeploying your app or editing anyone's config.

Use a virtual model to:

• Configure the model that coding agents and harnesses such as Claude Code or Codex use, including routing and provider options they can't send per request, and change it later without touching each developer's config.
• Change the model or routing your app uses without redeploying.
• Set provider order, fallbacks, fast mode, service tier, prompt caching, and provider options once per slug instead of on every request.
• Share one approved configuration across your team's apps, chat platforms, and other tools that list AI Gateway models.
• Enforce zero data retention or block provider training for all traffic through the slug.
• Tag requests for usage attribution.

Create a virtual model from the dashboard or the Vercel CLI.

vercel ai-gateway virtual-models create abc-123 --model anthropic/claude-opus-5.5

vercel ai-gateway virtual-models create coding-agent-eu \
  --model anthropic/claude-opus-5.5 \
  --provider-order bedrock,vertex \
  --config '{
    "inferenceRegion": { "scope": "zone", "geoRegion": "eu" },
    "providerOptions": { "anthropic": { "effort": "high" } },
    "observabilityTags": ["coding-agents"]
  }'

Coding agents send AI Gateway a model ID with each request, but they usually can't attach AI Gateway options such as provider order, model fallbacks, regional inference, or zero data retention. To give an agent those settings, create a virtual model and select vmc/<slug> as the agent's model, so every request the agent sends uses the virtual model's configuration. From the terminal, create the virtual model and connect your agents with vercel ai-gateway setup:

vercel ai-gateway virtual-models create coding-agent --model anthropic/claude-opus-5.5
vercel ai-gateway setup

AI Gateway lists your team's virtual models in the model catalogs it serves to coding agents, so the slug appears next to the catalog models:

• Claude Code: the /model picker lists claude-code/vmc/<slug>, with a [1m] suffix when the underlying model has a context window of 1M tokens or more.
• Codex: pick the slug from /model, pass codex --model vmc/<slug>, or set model = "vmc/<slug>" in ~/.codex/config.toml.
• Other agents: use vmc/<slug> anywhere the agent accepts an AI Gateway model ID.

AI Gateway lists only virtual models that point at a language model. If a running agent doesn't show a new slug yet, restart it so it reloads the model list.

Each agent stores only the slug, so editing the virtual model changes the configuration for every developer at once. For example, vercel ai-gateway virtual-models edit coding-agent --model anthropic/claude-fable-5.1 moves every agent using vmc/coding-agent to Fable 5.1 for new requests within a few minutes.

Once you create a virtual model, call it like any other AI Gateway model with the vmc/ prefix. The slug works in every request format AI Gateway supports, and you don't need to send any AI Gateway options with it. These examples use AI SDK 7 and the AI SDK for Python beta. Set AI_GATEWAY_API_KEY before running them. See API format differences for setup, request fields, and response handling:

import { generateText } from 'ai';
 
const { text } = await generateText({
  model: 'vmc/abc-123',
  prompt: 'Hello, world!',
});
 
console.log(text);

import asyncio
import ai
 
async def main():
    model = ai.get_model("vmc/abc-123")
    messages = [ai.user_message("Hello, world!")]
    async with ai.stream(model, messages) as stream:
        async for event in stream:
            if isinstance(event, ai.events.TextDelta):
                print(event.chunk, end="", flush=True)
    print()
 
asyncio.run(main())

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});
 
const response = await client.chat.completions.create({
  model: 'vmc/abc-123',
  messages: [{ role: 'user', content: 'Hello, world!' }],
});
 
console.log(response.choices[0]?.message.content);

import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://ai-gateway.vercel.sh/v1",
)
 
response = client.chat.completions.create(
    model="vmc/abc-123",
    messages=[{"role": "user", "content": "Hello, world!"}],
)
 
print(response.choices[0].message.content)

curl --fail-with-body https://ai-gateway.vercel.sh/v1/chat/completions \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vmc/abc-123",
  "messages": [{ "role": "user", "content": "Hello, world!" }]
}'

import Anthropic from '@anthropic-ai/sdk';
 
const client = new Anthropic({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh',
});
 
const message = await client.messages.create({
  model: 'vmc/abc-123',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello, world!' }],
});
 
for (const block of message.content) {
  if (block.type === 'text') console.log(block.text);
}

import os
from anthropic import Anthropic
 
client = Anthropic(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://ai-gateway.vercel.sh",
)
 
message = client.messages.create(
    model="vmc/abc-123",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, world!"}],
)
 
for block in message.content:
    if block.type == "text":
        print(block.text)

curl --fail-with-body https://ai-gateway.vercel.sh/v1/messages \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
  "model": "vmc/abc-123",
  "max_tokens": 1024,
  "messages": [{ "role": "user", "content": "Hello, world!" }]
}'

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});
 
const response = await client.responses.create({
  model: 'vmc/abc-123',
  input: 'Hello, world!',
});
 
console.log(response.output_text);

import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://ai-gateway.vercel.sh/v1",
)
 
response = client.responses.create(
    model="vmc/abc-123",
    input="Hello, world!",
)
 
print(response.output_text)

curl --fail-with-body https://ai-gateway.vercel.sh/v1/responses \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vmc/abc-123",
  "input": "Hello, world!"
}'

Click the vmc/<slug> pill on any row in the Virtual Models list to copy the full identifier to your clipboard.

Virtual models work with every model type in the AI Gateway catalog, including embedding, image, video, speech, transcription, reranking, and decision models. Pass the vmc/ slug to the AI SDK function for that model type, the same way you would pass the underlying model:

import { embed } from 'ai';
 
const { embedding } = await embed({
  model: 'vmc/search-embeddings',
  value: 'sunny day at the beach',
});

import { gateway } from '@ai-sdk/gateway';
import { generateImage } from 'ai';
 
const { image } = await generateImage({
  model: gateway.imageModel('vmc/product-images'),
  prompt: 'A red lighthouse on a rocky coast, flat illustration',
});

import { experimental_generateVideo as generateVideo } from 'ai';
import fs from 'node:fs';
 
const { videos } = await generateVideo({
  model: 'vmc/promo-video',
  prompt: 'A paper boat drifting down a rainy street, slow camera pan',
  duration: 5,
});
 
fs.writeFileSync('output.mp4', videos[0].uint8Array);

import { generateSpeech } from 'ai';
import { gateway } from '@ai-sdk/gateway';
import { writeFile } from 'node:fs/promises';
 
const result = await generateSpeech({
  model: gateway.speechModel('vmc/narrator'),
  text: 'Hello from AI Gateway.',
  voice: 'alloy',
});
 
await writeFile('greeting.mp3', result.audio.uint8Array);

import { transcribe } from 'ai';
import { gateway } from '@ai-sdk/gateway';
import { readFile } from 'node:fs/promises';
 
const result = await transcribe({
  model: gateway.transcriptionModel('vmc/meeting-notes'),
  audio: await readFile('meeting.mp3'),
});
 
console.log(result.text);

import { rerank } from 'ai';
 
const { ranking } = await rerank({
  model: 'vmc/search-rerank',
  query: 'What is the capital of France?',
  documents: [
    'Berlin is the capital of Germany.',
    'Paris is the capital of France.',
    'Madrid is the capital of Spain.',
  ],
  topN: 2,
});

import { experimental_decide as decide } from 'ai';
 
const { answers } = await decide({
  model: 'vmc/support-triage',
  state: 'Help! My payouts have been failing for 3 days.',
  questions: {
    urgent: { type: 'boolean', instructions: 'Is this request urgent?' },
  },
});

The same slugs work in the HTTP endpoints for each model type, such as /v1/embeddings, /v1/images/generations, /v2/rerank, and /v1/evaluate. In the AI SDK, providerMetadata.gateway.virtualModelConfig.modelId on the result names the virtual model that served the request.

A few things to keep in mind:

• Request options still belong to the underlying model. Options such as voice, size, or duration pass through unchanged, so use values the model behind the slug accepts.
• A slug only serves its own model type. Sending an image virtual model to Chat Completions, for example, returns a 400 error that names the API to use instead.
• Decision virtual models can store a fallback policy. See Decision Fallbacks to escalate uncertain answers to another model for every caller.

Your team's AI Gateway settings apply to every request, including requests through a virtual model. A virtual model can add restrictions for its own traffic, but it can't bypass or loosen a team setting:

Requests to vmc/<slug> go through the same AI Gateway routing as direct model requests, so many options can come from either side. The resolving rule depends on the field:

For example, vmc/coding-agent-eu from the diagram at the top of this page sets an EU inference region, provider order bedrock, vertex, the Anthropic provider option effort: high, and the tag coding-agents. It leaves prompt caching unset. A caller sends its own options anyway:

import { generateText } from 'ai';
 
const { text } = await generateText({
  model: 'vmc/coding-agent-eu',
  prompt: 'Review this diff for bugs.',
  providerOptions: {
    gateway: {
      order: ['anthropic'],
      tags: ['feature:review'],
      caching: 'auto',
      zeroDataRetention: true,
    },
    anthropic: {
      effort: 'low',
    },
  },
});

AI Gateway resolves each option like this:

• Provider order: AI Gateway tries bedrock, then vertex, in the EU. The virtual model sets an order, so the request's ['anthropic'] is ignored.
• Tags: AI Gateway records coding-agents. The request's feature:review tag is ignored.
• Prompt caching: auto, from the request, because the virtual model leaves caching unset.
• Zero data retention: on. The request turned it on, and neither side can turn it off.
• Reasoning effort: high. Provider options merge option by option, and the virtual model sets effort, so its value wins over the request's low.

A few details worth knowing:

• A setting the virtual model leaves unset still comes from the request. "Wins" applies only to settings the virtual model actually carries, so a slug can decide some options and leave the rest to the caller.
• Provider options combine option by option. Every other setting is a single value, so one side's wins outright. Provider options are a map, so the two are merged: the virtual model's value wins for each option it sets, and the request keeps the rest.
• Required capabilities replace, so check has: ['free']. A virtual model's capability list replaces the request's rather than adding to it, so a request using has: ['free'] to stay on free providers loses that guard if the slug sets its own capabilities.
• Compliance settings only tighten. Zero data retention and blocking prompt training turn on when either side enables them. A virtual model can't relax a restriction the request set, and a request can't relax one the virtual model set. In exchange, these fields reject the @default sentinel described below.
• Model fallbacks resolve per attempt. You can also use vmc/<slug> anywhere in a request's own model fallbacks array. Each model in a chain resolves independently, so a virtual model's routing and settings apply only to its own attempt and don't carry over to the next model in the list.
• Decision fallbacks rerun the full request. A decision virtual model can store one conditional policy. When it matches, AI Gateway reruns every question with the fallback and returns only that complete result. See Decision Fallbacks.

Sort, service tier, prompt caching, and provider timeouts are tri-state. Understanding the three states matters when a caller and a virtual model could both set the same option:

Use @default when a team wants to guarantee standard behavior for all traffic through a slug, for example to keep callers from pinning priority tier through a shared virtual model.

AI Gateway accepts @default only on sort, serviceTier, caching, and providerTimeouts. The compliance settings reject it because an off choice would loosen a restriction the caller asked for. speed, allowFallbackFromFast, and models reject it because their unset state already is the default behavior, and has rejects it too, so on those a virtual model either sets a value or leaves the caller's alone.

Changes to a virtual model, including archive and restore, take effect for new requests within a few minutes. The slug can't be changed after creation.

vercel ai-gateway virtual-models list

vercel ai-gateway virtual-models inspect coding-agent-eu

vercel ai-gateway virtual-models edit coding-agent-eu --model anthropic/claude-sonnet-5.5
vercel ai-gateway virtual-models edit coding-agent-eu --config '{"caching":"auto","serviceTier":"@default"}'
vercel ai-gateway virtual-models edit coding-agent-eu --config '{"inferenceRegion":null,"models":[]}'

vercel ai-gateway virtual-models remove coding-agent-eu
vercel ai-gateway virtual-models restore coding-agent-eu

Any member of your team can use a virtual model in their application. Team Owners and Members can create virtual models. Only the member who created a virtual model or a team Owner can edit, archive, remove, or restore it, in the dashboard or the CLI.

• vercel ai-gateway virtual-models CLI reference
• AI Gateway overview
• Provider filtering, ordering, and sorting
• Decision Fallbacks