Virtual Models

Virtual models are compatible with all model types on AI Gateway, including image, video, speech, embedding and real-time models.

The cost of virtual models is one extra hop of indirection; the benefits are decoupling configuration changes from code releases, enforceable compliance policies, and clearer spending attribution; for teams with a single application calling a single model, the benefits are limited.

Virtual models can be used for coding Agents, forcibly injecting settings such as reasoning effort, fast mode, and prompt caching into Agents that do not themselves expose these options, without waiting for Agent-side support.

Virtual models can specify which providers to use, configure fallback models, and enforce compliance requirements such as zero data retention (ZDR), so that compliance policies are enforced uniformly at the gateway layer rather than relying on each caller.

Each request using a virtual model can have custom reporting tags attached, making it easy to attribute spending to a specific project or team.

When using a virtual model, simply replace the original provider model ID with `vmc/<slug>` (such as `vmc/coding-agent`) in AI SDK or compatible API requests to invoke it.

For virtual models carrying production traffic, it is recommended to first create a candidate virtual model pointing to the new model and switch only after evaluation is complete; if quality drops, the original virtual model can be pointed back to the old model to roll back.

The Virtual Models page shows the request count, spending and success rate for each task.

After a virtual model's configuration is changed, all applications and Agents that call that ID automatically adopt the new configuration within a few minutes, with no code changes or redeployment needed.

Teams using coding Agents such as Claude Code and Codex can connect via vercel ai-gateway setup and select a virtual model in each harness's model selector or configuration.

Virtual model IDs should be named to reflect task semantics rather than model names (such as coding-agent, support-triage), avoiding names tied to a specific model (such as claude-opus-agent).

If a virtual model requires Zero Data Retention or disallowPromptTraining, these security policies remain enforced even if the request explicitly sets them to false.

Tags on a virtual model replace the tags carried in the request, so that spending is accurately attributed to specific tasks.

Gateway-level settings on a virtual model such as fallback, Zero Data Retention and tags switch along with the virtual model, but provider-specific options take effect per provider, so provider options need to be rechecked when switching providers.

Settings on a virtual model take precedence over settings of the same name in a request, and callers cannot override the provider order, fallback or service tier set by the virtual model.

AI Gateway has launched the "Virtual Models" feature, which abstracts model selection and parameter configuration from application code into configuration saved on the gateway side; callers invoke it via a custom model ID (such as vmc/coding-agent), and the underlying model and settings can be modified centrally without redeploying the application or Agent.

Vercel AI Gateway has launched a Virtual Models feature that abstracts model strings and configurations into reusable IDs, moving model switching from the code layer to the gateway layer.