# Model identifiers and discovery

Source: https://platform.lyrouter.com/ai_gateway/docs/model-names/en
Last updated: 2026-10-19

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

| Part | Examples | Description |
| --- | --- | --- |
| Vendor | `deepseek`, `qwen`, `anthropic`, `openai`, `google` | The part before the slash is the vendor that develops the model, not the provider that serves it. A model served by several providers still has only one model ID |
| Model name | `deepseek-v4-flash`, `qwen3.7-plus`, `claude-sonnet-4.6` | Includes the size and version number; the model catalog defines the exact spelling |

- **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](https://platform.lyrouter.com/ai_gateway/docs/versions/en).
- **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`):

| `model` in the request | Result |
| --- | --- |
| `deepseek/deepseek-v4-flash` | Correct |
| `DeepSeek/deepseek-v4-flash` | Not found (different case) |
| `deepseek-v4-flash` | Not found (missing vendor prefix); Codex clients are an exception, see below |
| `deepseek/deepseek-v4-flash ` (trailing space) | Not found |
| `anthropic/claude-sonnet-4-6` | Not found (different version spelling) |
| `DeepSeek V4 Flash` | Not found (display name) |
| `ep-20260101xxxxxx-xxxxx` | Not found (the provider's endpoint ID) |

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](https://platform.lyrouter.com/ai_gateway/docs/routing/en#default-model).

## Special names

| Name | Purpose | Rules |
| --- | --- | --- |
| `@vmodel/<name>` | Calls an enabled [virtual model](https://platform.lyrouter.com/ai_gateway/docs/presets/en) in the workspace | `<name>` contains only lowercase letters, digits and hyphens, starts with a letter or digit, and is case-sensitive. The old prefix `@preset/<name>` is equivalent |
| `lyrouter/auto` | Picks among the enabled models by task difficulty; see [Auto routing](https://platform.lyrouter.com/ai_gateway/docs/auto/en) | Fixed spelling |

- **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](https://platform.lyrouter.com/ai_gateway/docs/embeddings/en) and [Rerank documents](https://platform.lyrouter.com/ai_gateway/docs/rerank/en)). 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](https://platform.lyrouter.com/ai_gateway/docs/codex/en).

## BYOK and upstream model names

After you connect your own provider credentials through [BYOK](https://platform.lyrouter.com/ai_gateway/docs/byok/en), 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:

| Name | Example | Where it is used |
| --- | --- | --- |
| Model ID | `deepseek/deepseek-v4-pro` | The request's `model`, virtual models, the Auto candidate scope, guardrail model policies |
| Upstream model name | `deepseek-v4-pro`, or a Volcano Engine Ark `ep-*` endpoint ID | Only in the requests the gateway sends to the provider, as set by the BYOK model mapping |

- **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](https://platform.lyrouter.com/ai_gateway/docs/mapping/en).
- **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

| Where | What you get | Best for |
| --- | --- | --- |
| The workspace's **Model marketplace** | Enabled models with their providers and prices; click the copy button next to the model ID | Choosing a model by hand; see [Choosing a model](https://platform.lyrouter.com/ai_gateway/docs/choose/en) |
| [`GET /v1/models`](https://platform.lyrouter.com/ai_gateway/docs/models/en) | The model IDs this API key can call, plus enabled `@vmodel/<name>` names and `lyrouter/auto` | Getting the list from a program, filling a model picker |
| The **Virtual models** page | The call names of virtual models | The current Account Owner managing virtual models; Account Members look up names with `GET /v1/models` |

`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](https://platform.lyrouter.com/ai_gateway/docs/authorization/en). If it is listed and the call still fails, look up the error message in [Unavailable models](https://platform.lyrouter.com/ai_gateway/docs/unavailable/en).

### 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](https://platform.lyrouter.com/ai_gateway/docs/presets/en) 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](https://platform.lyrouter.com/ai_gateway/docs/tools/en).

### 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](https://platform.lyrouter.com/ai_gateway/docs/claude-code/en), all with LYRouter model IDs, then check Model (request) in the logs to confirm none were missed.