# Models and routing

Model ids, the Global and Russia regions, fallback models and the provider object.

## Model ids

A request names a model, never a server. The [catalog](/models) and `GET /api/v1/models` list every available model.

| Id                 | Region                      | Example                                      |
| ------------------ | --------------------------- | -------------------------------------------- |
| `vendor/model`     | Global: providers worldwide | `google/gemma-3-4b-it`, `openai/gpt-4o-mini` |
| `ru-1/…`, `ru-2/…` | Russia: hosted in Russia    | `ru-1/openai/gpt-oss-120b`                   |

Ids are exact: there are no aliases and no variant suffixes. An unknown id is a `400` with the message `model … is not available`.

Every model is served in one region only. The same open-weight model may exist twice, for example `openai/gpt-oss-120b` (Global) and `ru-1/openai/gpt-oss-120b` (Russia): these are two models with their own prices.

## How a request is routed

For each model of the request the router picks its route, then:

1. skips routes that do not support what the request needs: `tools` needs tool calling, `response_format` with `json_schema` needs structured output;
2. applies the `provider` preferences below;
3. puts routes that failed recently last.

If no route of a model is left, the router moves on to the next model of `models`; with none left it answers `400` with the message `no route of … satisfies the provider constraints and parameters`.

## Fallback models

`models` lists models to try, in order, after `model`:

```json
{
  "model": "openai/gpt-4o-mini",
  "models": ["google/gemma-3-4b-it", "ru-1/openai/gpt-oss-120b"],
  "messages": [{ "role": "user", "content": "Hello" }]
}
```

- The next model is tried when a model has no route, or its provider fails **before the first token**: a timeout, a `5xx`, a `429`, or a `404`.
- A request makes at most **3 attempts** in total.
- Once the answer has started, the router never switches models.
- `model` in the response says which model answered; `GET /api/v1/generation` lists every attempt.
- Attempts the provider rejected with an error are not billed. Funds are reserved for the most expensive model of the list, so a long list needs a larger balance.

> **Warning:** A `models` list may cross regions. Add `"provider": {"ignore": ["ru"]}` to stay in the Global region, or `"provider": {"zdr": true}` to stay on providers that keep no data.

## The provider object

| Field                       | Effect                                                                                                    |
| --------------------------- | --------------------------------------------------------------------------------------------------------- |
| `"only": ["ru"]`            | Only the Russia region: the request never leaves Russia.                                                  |
| `"ignore": ["ru"]`          | Never the Russia region.                                                                                  |
| `"order": [...]`            | The order of providers to try; `ru` puts the Russia region in that place.                                 |
| `"allow_fallbacks": false`  | One route per model: no fallback between routes of a model. The `models` list still applies.              |
| `"zdr": true`               | Only models with a zero data retention endpoint. See [Zero data retention](/docs/en/zero-data-retention). |
| `"data_collection": "deny"` | Only providers that do not store or train on data; excludes the Russia region.                            |

Other slugs in `only`, `ignore` and `order`, and other keys of the object (for example `sort` or `max_price`), are passed to the Global region as is, without guarantees.

## Keep data in Russia

To make sure nothing leaves the country, use a `ru-1/…` or `ru-2/…` model and add `"provider": {"only": ["ru"]}`: then even a `models` list with Global models cannot leave Russia.

```json
{
  "model": "ru-1/openai/gpt-oss-120b",
  "provider": { "only": ["ru"] },
  "messages": [{ "role": "user", "content": "Привет" }]
}
```

Fields that work only in the Global region are removed for Russia models; see [Parameters](/docs/en/parameters#how-the-router-treats-parameters).