Model identifiers and discovery

Set the request's model to a model ID in the form vendor/model (for example deepseek/deepseek-v4-flash). It is case-sensitive and must match the value shown in the model marketplace or returned by GET /v1/models character for character. There are also two kinds of special names: @vmodel/<name> calls a virtual model, and lyrouter/auto calls Auto routing. Clients always send the model ID; the gateway substitutes the provider's real model name (including a BYOK endpoint ID), so do not put that name in the request.

Model ID format

• Exact match: case and punctuation must be exactly the same as the model ID in the catalog, with no leading or trailing spaces. The gateway does not change case, does not add a vendor prefix and does not treat similar names as the same model.
• Copy version numbers as written: the version in anthropic/claude-sonnet-4.6 uses a dot; anthropic/claude-sonnet-4-6 does not find this model.
• Different versions have different IDs: different sizes and versions in the same family use different model IDs, and the gateway never points an old ID to a new version automatically. Steps for switching versions are in Model versions and retirement.
• Display names cannot be called: the card title in the model marketplace (such as "DeepSeek V4 Flash") is for display only; the same applies to display_name in GET /v1/models.

The table below shows what common spellings do (assuming the workspace has enabled deepseek/deepseek-v4-flash and anthropic/claude-sonnet-4.6):

What happens when a name is not found depends on whether the workspace has a Default Model set in Smart routing:

• A Default Model is set: chat-style requests are answered by the Default Model instead, with HTTP status 200. Your program gets an answer, but not from the model you meant to call.
• No Default Model is set: the request returns 403 Model is not available in the model plaza (error.code model_not_available).

In Log analysis, compare Model (request) with Model (actual): when they differ and Model (actual) is the Default Model, the name in the request did not match. How the Default Model behaves is covered in Channels and routing.

Special names

• Supported endpoints: lyrouter/auto works only with /v1/chat/completions, /v1/messages and /v1/responses. Besides these three, virtual models can also be used on the embeddings and rerank endpoints (their model list must then consist entirely of embedding or rerank models; see Create embeddings and Rerank documents). Both return 403 Model is not available in the model plaza on image and video endpoints.
• When a name stops working: after a virtual model is disabled, deleted or renamed, the old name no longer matches. If a Default Model is set, it answers; otherwise the request returns 503 all routed candidates exhausted.
• How they appear in the logs: when you call through either kind of name, Virtual model in the log's Route trace shows the virtual model name (without @vmodel/) or lyrouter/auto, and Model (actual) shows the model that actually answered.

Omitting model

When the request body has no model, or model is "" or null, the gateway uses the workspace's Default Model. Without a Default Model, the request returns 400 you must provide a model parameter (missing_model); when model is not a string, it returns 400 invalid type for 'model': expected a string (invalid_model). In production code, always name the model ID, so that behavior does not change when the Default Model is adjusted.

Name completion for Codex clients

Some Codex screens only let you pick model names without a vendor prefix (such as gpt-5.5). When the gateway recognizes a request from a Codex client, it adds openai/ to model names that contain no slash, so gpt-5.5 is called as openai/gpt-5.5. Names that already contain a slash are not affected, and other clients get no such completion. To call non-OpenAI models from Codex, enter the full model ID in the configuration file; see Codex.

BYOK and upstream model names

After you connect your own provider credentials through BYOK, clients still send the model ID, and the gateway replaces it with the mapped upstream model name when it sends the request to the provider:

• Upstream names are not model IDs: an upstream name such as ep-* in the request is treated as "not found"; see above.
• One model ID can map to different upstream names: platform channels and each BYOK channel have their own mappings, and the gateway substitutes the one for the channel it actually selects. Client code does not need to care which.
• Custom providers also map to model IDs: each upstream model of a custom provider must correspond to a model in the platform model catalog; you cannot create new model IDs. See Model mappings and sources.
• Checking the name actually sent: in the log detail, open Upstream request under Raw packets; its model is the upstream model name. Bodies are stored only after the workspace turns on content logging, except for failed requests.

The model field in the response body is the value returned by the upstream, usually the upstream model name, and is not necessarily the model ID you sent. When your program needs to record "which model was called", record the model ID it sent, or go by Model (actual) in the logs.

Finding available names

GET /v1/models is already filtered by guardrail model policies, so it is closer than the model marketplace to "what this key can actually call".

FAQ

I can see the model in the model marketplace. Why is it not found when I call it?

Answer: First confirm it is under Workspace models, not Available or Needs connection. Then request GET /v1/models with the API key you call with, and confirm the ID is in the list. If it is not, the model has not been enabled, or a guardrail model policy restricts it; see Model access. If it is listed and the call still fails, look up the error message in Unavailable models.

My client only accepts model names without a slash. What can I do?

Answer: For Codex, the gateway adds the openai/ prefix automatically. For other clients that accept only fixed names, create a virtual model and enter @vmodel/<name> in the client; if the client accepts neither @ nor /, switch to a client or configuration method that supports custom model names; see Tools and compatibility.

Requests from Claude Code use official Claude model names. Why do they fail?

Answer: Claude Code's background tasks and model aliases use official Claude model names (such as claude-haiku-4-5), which are not LYRouter model IDs. Fill in every model variable as described in Claude Code, all with LYRouter model IDs, then check Model (request) in the logs to confirm none were missed.