Skip to content
Docs

Create virtual model config

POSThttps://api.vercel.com/ai-gateway/virtual-model-configs
Create a virtual model config (VMC)
https://api.vercel.com/ai-gateway/virtual-model-configs
const response = await fetch('https://api.vercel.com/ai-gateway/virtual-model-configs?teamId=string&slug=string', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
});


const data = await response.json();
console.log(data);
Response
{
  "allowFallbackFromFast": "false",
  "baseUrl": "https://example.com",
  "byokCredentialIds": [],
  "caching": "auto",
  "createdAt": "123",
  "createdBy": "string",
  "deleted": "false",
  "description": "string",
  "disallowPromptTraining": "false",
  "displayName": "Example Name",
  "has": [],
  "hipaaCompliant": "false",
  "inferenceRegion": {
    "geoRegion": "string",
    "providerRegion": "example_id",
    "providers": "value",
    "scope": "global"
  },
  "instanceId": "example_id",
  "kind": "string",
  "models": [],
  "modelSlug": "string",
  "observabilityTags": [],
  "ownerId": "example_id",
  "providerOnly": [],
  "providerOptions": "value",
  "providerOrder": [],
  "providerTimeouts": {
    "byok": "value"
  },
  "selector": "cost",
  "selectorOptions": {
    "cost": "value",
    "tps": "value",
    "ttft": "value"
  },
  "serviceTier": "fast",
  "sort": "cost",
  "speed": "fast",
  "status": "string",
  "updatedAt": "123",
  "updatedBy": "string",
  "virtualModelSlug": "string",
  "visibility": "string",
  "zeroDataRetention": "false"
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Query parameters

teamIdstringOptional
The Team identifier to perform the request on behalf of.
slugstringOptional
The Team slug to perform the request on behalf of.

Response

201Success
allowFallbackFromFastbooleanOptional
Allow fallback from fast to standard providers on failure.
baseUrlstringOptional
For kind=relay: URL the gateway forwards requests to as a transparent proxy.
byokCredentialIdsarrayOptional
BYOK credential IDs allowed for this VMC.
cachingstringOptional
Use caching if available.
createdAtnumberRequired
Creation timestamp (epoch ms).
createdBystringOptional
User or app id that created this VMC.
deletedbooleanRequired
Whether this VMC is soft-deleted.
descriptionstringOptional
Optional description for UI.
disallowPromptTrainingbooleanOptional
Only use providers that will not train on your prompts.
displayNamestringOptional
Human-readable name for UI.
hasarrayOptional
Limit providers to those with these features.
hipaaCompliantbooleanOptional
Only use HIPAA-compliant providers.
inferenceRegionobjectOptional
Region pinned on the VMC for system-credential routing (alias/router only).
instanceIdstringOptional
The concrete model-provider instance this VMC resolves to.
kindstringRequired
VMC kind: alias, relay, or router.
modelsarrayOptional
For kind=router: ordered candidates, bare slugs/references or { slug, ...attributes }. For kind=alias: ordered fallback model slugs, optionally led by one conditional { model, when } entry, used when the primary model's answers match when.
modelSlugstringOptional
Canonical model slug this VMC maps to (e.g. "creator/model"). Not used by kind=router.
observabilityTagsarrayOptional
Observability tags attached to requests through this VMC.
ownerIdstringRequired
Team (owner) that owns this VMC.
providerOnlyarrayOptional
Restrict routing to only these providers.
providerOptionsobjectOptional
Arbitrary per-provider AI SDK options, keyed by gateway provider slug.
providerOrderarrayOptional
Ordered list of providers to try as fallbacks on failure.
providerTimeoutsobjectOptional
Per-request provider timeouts in ms, keyed by provider slug for BYOK credentials.
selectorstringOptional
For kind=router: how to order candidates. Absent means declared order.
selectorOptionsobjectOptional
For kind=router: option slices keyed by selector name; each selector owns its slice's shape.
serviceTierstringOptional
Service tier for providers that support it.
sortstringOptional
Rank eligible providers by an attribute.
speedstringOptional
Only use fastest providers with short timeouts.
statusstringRequired
UI lifecycle status: draft, active, or archived.
updatedAtnumberRequired
Last update timestamp (epoch ms).
updatedBystringOptional
User or app id that last updated this VMC.
virtualModelSlugstringRequired
Client-facing alias used as the model slug in Gateway calls.
visibilitystringOptional
Visibility in listings: public, internal, or stealth.
zeroDataRetentionbooleanOptional
Only use providers with zero data retention.

Errors

400Error
401The request is not authorized.
403You do not have permission to access this resource.
404Error
409Error
410Error
429Error
500Error