# Models

> How model IDs work, how to discover models and their provider endpoints, what the published statistics mean, and how listed prices relate to what you pay.

Source: https://0.0.0.0:3000/docs/models
Documentation index: https://0.0.0.0:3000/docs/llms.txt

Every model on Numes has one canonical ID, the same on every provider that serves it. You send that ID in `model`, and routing picks one of the model's approved provider endpoints.

## Available supply

Model lists and endpoint discovery use completed snapshots captured every
30 seconds by default. New offers, prices and model details appear with the
next completed publication, normally within about 30 seconds. New sorts based
on measurements and freshness filters require supply no more than one minute old and
statistics coverage no more than two minutes old, by default. Statistics
publish once a minute; the default popularity order can use older published
counts during an outage.

Ordinary browsing and compatible inventory can use completed supply up to five
minutes old with explicit freshness. Older or uninitialized supply returns 503.
Pages keep their snapshot for at most five minutes from capture and recheck
current access on every request. Routing rechecks authorization, funds and
capacity before dispatch.

## Model IDs

A model ID is a canonical `author/model` slug, for example `openai/gpt-6-luna`. It matches:

```text
^[a-z0-9][a-z0-9._-]{0,99}/[A-Za-z0-9][A-Za-z0-9._:-]{0,254}$
```

- The **author** part is lowercase: letters, digits, `.`, `_` and `-`, up to 100 characters.
- The **model** part may use mixed case, digits, `.`, `_`, `:` and `-`, up to 255 characters.

The catalogue owns these IDs. When a provider publishes a model, the platform binds it to a canonical ID through review. A name alone never establishes identity: two providers that call a model by the same name aren't merged unless review shows they serve the same release, and a quantized or fine-tuned variant isn't treated as the original. A provider's own name for the model is used only to send it your request; responses, usage records and generation metadata always carry the canonical ID.

- **Send exactly one model.** Use `model`, or `models` with exactly one entry. For a second model when the first is unavailable, see [Model fallback](/docs/routing/fallbacks#model-fallback).
- **No aliases or variants.** `~author/model` aliases, router models such as `openrouter/auto`, and suffixes such as `:free`, `:nitro` or `:floor` aren't supported. Use [provider routing](/docs/routing/provider-routing) to prefer cheap or fast endpoints.
- **Client prefixes aren't part of the ID.** Coding agents such as OpenCode often show a model as `<provider-name>/author/model`, where the first segment is the name you configured in that client. The client strips it before sending.

Two suffixes qualify a model ID, and you can combine them as `author/model:e2ee:org-team`:

- `:e2ee` marks an end-to-end encrypted model, shown with a lock on web pages. It requires the [encrypted client path](/docs/inference/encrypted); ordinary completion requests reject it.
- `:org-<handle>` marks a model shared with one of your organizations. `GET /models` describes it in the `access` field, and web pages mark it with a building icon. The dashboard **Models** page and the chat model picker can filter by organization.

## Browse the catalogue

| Where | Sign-in | Prices shown in | Best for |
| --- | --- | --- | --- |
| [Models](/models) public catalogue | Not required | US dollars, per 1M tokens | Comparing models, endpoints and measured performance |
| Dashboard **Models** | Required | USD or BTC, selectable | Filtering and sorting by task, encryption, organization, parameters, hosted tools, price and measured performance |
| `GET /models` API | Inference key | Your key's currency, per unit | Programmatic discovery and client configuration |

Choosing a display currency doesn't change billing or the funds a request needs.

The table below reads the public catalogue live. Copy an ID, or choose the play button to open the playground with that model. Encrypted models have no play button: the playground can't encrypt requests.

```live-models
{ "limit": 50 }
```

Each model page shows the canonical ID, context and output limits, modalities, every routable endpoint with its prices, and [endpoint statistics](#endpoint-statistics). An endpoint that charges more than input and output rates, such as cache, reasoning, image, request or hosted-tool rates, has a rates button that opens all of them. Web pages show token prices per million tokens and per-unit prices per thousand; the API returns exact per-unit rates.

Each model page names the model's lab, the company that makes it, above the model name. The lab is the part of the model ID before the slash. Select it to open the lab page, at `/models/<lab>` on the public site and `/dashboard/models/<lab>` in the dashboard. It shows the lab's logo and name, a short description and a link to the lab's website where one is known, and every model from that lab in the catalogue, with the same search, filters, sorting and statistics as the full list. The catalogue's **Lab** filter and sort use the same lab.

## Endpoint statistics

Each model page charts every endpoint over the last hour, 24 hours, 7 days (the default) or 30 days, computed from real requests:

| Chart | What it shows |
| --- | --- |
| **Success rate** | Share of requests completed without a provider error |
| **Time to first token** | Median time from sending the request to the provider until its first output, shaded to p90 |
| **Throughput** | Median output tokens per second between the first and last output, shaded to p90 |
| **Task quality** | Share of checked tool-call and structured responses that passed validation; see [Quality sort](/docs/routing/provider-routing#quality-sort) |

- **Success rate** counts outcomes the provider is responsible for. Your own cancellations and invalid requests don't lower it.
- **Time to first token** is measured at the platform. It excludes your network, so your client observes somewhat more.
- Every value shows how many requests it's based on. Periods without requests are gaps, never zeros.

Statistics describe what happened, not live status. A quiet endpoint can be ready now with no recent data, and an endpoint with a strong history can still fail the next request. Routing uses live health; use the charts to compare endpoints over time. For your own traffic, [Activity](/docs/account/activity) reports latency, time to first token and throughput per request.

Catalogue and provider-directory lists use the selected time window for request counts, success and error rates, latency, throughput and task quality. Every figure covers that whole window; an offer without requests in it shows no statistics for that window. Task quality reports one exact contract profile, such as tool calls or structured output, with its own sample count. Changing the sort preserves that window. Latency and throughput sorts place entries without timing samples after comparable measured entries in either direction.

## List models

```endpoint
GET /api/v1/models
```

Returns every model that has a routable offer in your key's currency, one row per model, ordered by model ID unless you set `sort`. Requires an inference key.

```request
{
  "method": "GET",
  "path": "/models"
}
```

:::fields Query parameters
- `output_modalities` `string` — Comma-separated output modalities. A model is kept when at least one of its offers produces every listed modality. Omit the parameter, send an empty value or send `all` to apply no filter.
- `supported_parameters` `string` — Comma-separated parameter names. A model is kept when at least one of its offers declares every listed parameter.
- `sort` `string` — `pricing-low-to-high` or `pricing-high-to-low` (prompt plus completion rate), `context-high-to-low`, or `newest` (by `created`).
:::

Filters must match on the **same offer**. If a model's tool-capable endpoint and its JSON Schema-capable endpoint are different, the model doesn't match `supported_parameters=tools,structured_outputs`, because no single endpoint could serve a request that needs both. A matching row describes one of the matching offers.

| `output_modalities` value | Models kept |
| --- | --- |
| `text` | Chat models that produce text |
| `image` | Image generation models |
| `embeddings` | Embedding models |
| `speech` | Text-to-speech models for [`/audio/speech`](/docs/multimodal/speech) |
| `transcription` | Speech-to-text models for [`/audio/transcriptions`](/docs/multimodal/audio) |
| `audio` | Chat models that declare audio output |

Values are case-sensitive. With no filter the list includes every task, so filter on `text` when you need chat models only. There's no pagination or free-text search; use the dashboard or the public catalogue to search.

Chat models that support tool calling and JSON Schema output, cheapest first:

```request
{
  "method": "GET",
  "path": "/models",
  "query": {
    "output_modalities": "text",
    "supported_parameters": "tools,structured_outputs",
    "sort": "pricing-low-to-high"
  }
}
```

## The model object

```json title="Response"
{
  "data": [
    {
      "id": "openai/gpt-6-luna",
      "canonical_slug": "openai/gpt-6-luna",
      "name": "Example Model",
      "description": "A general-purpose instruction-tuned model.",
      "created": 1785000000,
      "context_length": 131072,
      "architecture": {
        "modality": "text+image->text",
        "input_modalities": ["text", "image"],
        "output_modalities": ["text"],
        "tokenizer": "example"
      },
      "pricing": {
        "prompt": "0.0000002",
        "completion": "0.0000008",
        "request": "0",
        "image": "0",
        "audio": "0",
        "input_cache_read": "0.00000005"
      },
      "supported_parameters": [
        "max_tokens", "reasoning", "response_format", "seed", "stop",
        "structured_outputs", "temperature", "tool_choice", "tools", "top_p"
      ],
      "top_provider": { "context_length": 131072, "max_completion_tokens": 32768 },
      "billing_currency": "USD",
      "maximum_output_length": 32768,
      "embeddings": false,
      "reasoning": {
        "default_effort": "medium",
        "default_enabled": true,
        "mandatory": false,
        "supports_max_tokens": true,
        "supported_efforts": ["low", "medium", "high"]
      }
    }
  ]
}
```

:::fields Model
- `id` `string` required — Model ID to send in `model`, including any `:e2ee` or `:org-<handle>` qualifier.
- `canonical_slug` `string` required — The canonical `author/model` ID without qualifiers.
- `name` `string` required — Display name.
- `description` `string` — Catalogue description. May be empty.
- `created` `integer` required — Release time in Unix seconds, as recorded in the catalogue.
- `context_length` `integer` required — Context window of the row's offer, in tokens. Your prompt plus `max_tokens` must fit inside it.
- `max_input_tokens` `integer` — Separate input ceiling of the row's offer, when declared. The prompt must fit this as well as the context window.
- `architecture` `object` required — Modalities and tokenizer of the row's offer.
  - `modality` `string` — Summary such as `text+image->text`.
  - `input_modalities` `string[]` — Accepted inputs: `text`, `image`, `file` (PDF) or `audio`.
  - `output_modalities` `string[]` — Produced outputs: `text`, `image`, `audio`, `embeddings`, `speech` or `transcription`.
  - `tokenizer` `string` — Tokenizer family recorded for the model.
- `pricing` `object` required — Exact per-unit rates of the row's offer. See [Pricing object](#pricing-object).
- `supported_parameters` `string[]` required — Request parameters the row's offer declares. See [Supported parameters](#supported-parameters).
- `top_provider` `object` — Limits of the row's offer. Always present.
  - `context_length` `integer` — Context window in tokens.
  - `max_completion_tokens` `integer | null` — Output maximum, or `null` when the offer doesn't declare one.
- `billing_currency` `string` — `USD` or `BTC`: the currency of your key and of every price in the row.
- `usage_meter` `string` — Identifier of the measurement that counts billable units for the offer. Treat it as opaque.
- `maximum_output_length` `integer` — Largest `max_tokens` the offer accepts, capped at the platform's [output limit](/docs/api-reference/parameters#output-length). Omitted when unknown.
- `embeddings` `boolean` — `true` for embedding models.
- `supported_hosted_tools` `string[]` — Versioned hosted tool IDs such as `openrouter.web_search@1`. Omitted when the offer has none. See [Hosted tools](/docs/features/hosted-tools).
- `reasoning` `object` — Present only when the offer supports the `reasoning` parameter and has published reasoning details.
  - `default_effort` `string | null` — Effort used when you don't set one.
  - `default_enabled` `boolean` — Whether reasoning runs when you send no reasoning controls.
  - `mandatory` `boolean` — `true` when reasoning can't be turned off.
  - `supports_max_tokens` `boolean` — Whether `reasoning.max_tokens` is accepted.
  - `supported_efforts` `string[]` — Accepted values of `reasoning.effort`, from `none`, `minimal`, `low`, `medium`, `high`, `xhigh` and `max`.
- `access` `object` — Present only on a model shared with one of your organizations.
  - `kind` `string` — `organization`.
  - `organization` `object` — The organization's `handle` and `display_name`.
:::

A missing `reasoning.supported_efforts` list doesn't mean every effort is accepted. Sending an effort the offer doesn't declare excludes that offer from routing. The exception is an offer that supports `reasoning` but has no `reasoning` object: its effort levels are unknown, so it receives your effort as a hint. See [Reasoning](/docs/features/reasoning#routing-requirements).

### Pricing object

All values are decimal strings, per unit, in your key's currency: US dollars for a USD key, sats for a BTC key.

:::fields Pricing
- `prompt` `string` required — Rate per prompt token. `"0"` when the offer has no rate for this category.
- `completion` `string` required — Rate per completion token, including visible reasoning.
- `request` `string` required — Flat rate per request.
- `image` `string` required — Rate per image or megapixel, as the provider declared it.
- `audio` `string` required — Rate for audio, speech or transcription usage, in the unit the provider declared.
- `input_cache_read` `string` — Rate per prompt token read from cache. Omitted when the offer has no cache-read rate; `"0"` means reads are free.
- `input_cache_write` `string` — Rate per prompt token written to cache. Same absent-versus-zero rule.
- `pricing_basis` `string` — `usd_indexed` when the offer is priced in dollars but charged in sats. Omitted for fixed prices.
- `reference` `object` — Present with `usd_indexed`: the BTC/USD reference behind the sat rates shown, with its `id`, `policy`, `usd_per_btc` rate, `observed_at` and `expires_at` times.
- `usd_rates` `object` — Present with `usd_indexed`: the provider's dollar rate for each category above.
:::

When an offer has several rates in one category, such as conditional tiers, the lowest is shown. Cache rates are never higher than the prompt rate. For USD-indexed offers, the reference is refreshed regularly and the sat rate is locked for each request, so a later update never changes the price of a request already running.

### Supported parameters

Common values in `supported_parameters`:

| Value | Meaning |
| --- | --- |
| `max_tokens` | Accepts an output limit through `max_tokens` or `max_completion_tokens` |
| `temperature`, `top_p`, `top_k`, `seed`, `stop` | Sampling controls forwarded to the model |
| `tools` | Function calling |
| `tool_choice` | Forcing, naming or disabling tool calls |
| `parallel_tool_calls` | Control over multiple calls in one turn |
| `response_format` | JSON object mode |
| `structured_outputs` | JSON Schema output through `response_format.json_schema` |
| `reasoning` | Reasoning controls; details are in the `reasoning` object |
| `include_reasoning` | The legacy reasoning visibility flag |
| `cache_control`, `prompt_cache_options`, `prompt_cache_breakpoint` | Prompt cache directives; see [Prompt caching](/docs/features/prompt-caching). Endpoints without `cache_control` still serve requests that mark messages or text parts, without the markers |
| `prompt_cache_key` | Accepts the opaque cache hint; endpoints without it still serve requests that send a key |

Endpoints for other tasks may list additional controls. Features such as tools, JSON output, reasoning efforts and cache directives are hard routing requirements: a request that uses them only reaches offers that support them. Offers with unpublished effort levels are the one exception; see [Reasoning](/docs/features/reasoning#routing-requirements). Sampling controls the chosen offer doesn't declare are dropped unless you set [`provider.require_parameters`](/docs/routing/provider-routing#require-parameters).

## One row, one offer

A model served by several endpoints may have different limits, parameters and prices on each. Instead of merging them into a union no single endpoint supports, each row describes one **representative offer**, chosen deterministically. Every field in the row, including `pricing`, `context_length` and `supported_parameters`, comes from that offer.

The representative offer isn't necessarily the cheapest, and it doesn't pin routing: any eligible endpoint can serve your request. Price sorts compare representative offers. To see every endpoint, use the endpoints API below.

## Which models appear

A model is listed only when at least one of its offers can take requests:

- The provider, endpoint and offer are approved and active, and the model's public ID passed review.
- The offer passes [verification](/docs/routing/verification) and isn't failing repeatedly.
- The offer is priced in your key's currency.

The last rule means the list depends on the key: a BTC key sees only offers priced in BTC, and a USD key only USD offers. The public catalogue shows US dollar prices. If a model appears on the website but not in your `GET /models` response, check your key's currency with [`GET /key`](/docs/api-reference/keys/get-current-key).

Listings are refreshed continuously and can trail supply changes briefly. Responses carry `X-Catalogue-*` headers with the listing's capture time and whether it's stale, and return `503` when no recent listing is available. Being listed doesn't guarantee a request will succeed at that moment: routing rechecks health, capacity, your request's size and parameters, and your price limits for every request. See [Provider routing](/docs/routing/provider-routing).

## List a model's endpoints

```endpoint
GET /api/v1/models/{author}/{slug}/endpoints
```

Returns the model and every eligible offer in your key's currency, ordered by provider name, then endpoint name. An unknown model, or one with no offer in your key's currency, returns `404 not_found`. The list comes from the same listing as `GET /models`, so the two agree.

```request
{
  "method": "GET",
  "path": "/models/openai/gpt-6-luna/endpoints"
}
```

```json title="Response"
{
  "data": {
    "id": "openai/gpt-6-luna",
    "name": "Example Model",
    "created": 1785000000,
    "description": "A general-purpose instruction-tuned model.",
    "architecture": {
      "modality": "text+image->text",
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "tokenizer": "example"
    },
    "endpoints": [
      {
        "name": "Example Provider: eu-west",
        "provider_name": "Example Provider",
        "tag": "example-provider/eu-west",
        "context_length": 131072,
        "max_prompt_tokens": 131072,
        "max_completion_tokens": 32768,
        "maximum_output_length": 32768,
        "quantization": "fp8",
        "pricing": {
          "prompt": "0.0000002",
          "completion": "0.0000008",
          "request": "0",
          "image": "0",
          "audio": "0",
          "input_cache_read": "0.00000005"
        },
        "supported_parameters": ["max_tokens", "response_format", "temperature", "tool_choice", "tools"],
        "input_modalities": ["text", "image"],
        "output_modalities": ["text"],
        "billing_currency": "USD",
        "embeddings": false
      }
    ]
  }
}
```

:::fields Endpoint
- `tag` `string` — Routing selector in the form `provider/endpoint`. Use it in `provider.order`, `only` and `ignore` to target this endpoint.
- `name` `string` required — `Provider name: Endpoint name`, for display.
- `provider_name` `string` required — Provider display name. Display names can change; use `tag` in code.
- `context_length` `integer` required — Context window in tokens.
- `max_prompt_tokens` `integer` — Largest prompt the endpoint accepts: its separate input ceiling when declared, otherwise its context window.
- `max_completion_tokens` `integer | null` — Output maximum, or `null` when not declared.
- `maximum_output_length` `integer` — Output maximum capped at the platform's output limit. Omitted when unknown.
- `quantization` `string | null` — Declared weight precision: `int4`, `int8`, `fp4`, `mxfp4`, `nvfp4`, `fp6`, `fp8`, `mxfp8`, `fp16`, `bf16` or `fp32`. `null` when not declared.
- `pricing` `object` required — Exact per-unit rates of this endpoint, with the same fields as the [pricing object](#pricing-object).
- `supported_parameters` `string[]` required — Parameters this endpoint declares.
- `input_modalities` `string[]` — Inputs this endpoint accepts.
- `output_modalities` `string[]` — Outputs this endpoint produces.
- `reasoning` `object` — Reasoning facts of this endpoint, when it supports `reasoning`.
- `billing_currency` `string` — Currency of the prices: your key's currency.
- `usage_meter` `string` — Identifier of the measurement that counts billable units. Treat it as opaque.
- `embeddings` `boolean` — `true` for embedding endpoints.
- `supported_hosted_tools` `string[]` — Hosted tools this endpoint runs. Omitted when none.
- `uptime_last_30m` `number | null` — Reserved for OpenRouter compatibility and not populated. Use the [endpoint statistics](#endpoint-statistics) instead.
:::

The top-level `architecture` describes the canonical model; each endpoint's modalities describe what that endpoint serves.

## How listed prices become your charge

Listed prices are the provider's rates. There's no per-request platform markup: the platform fee is collected when you buy credits (see [Credits](/docs/account/credits)).

```text
usage.cost = Σ (billable quantity × listed rate)
```

- **Billable quantities** come from the usage the platform accepts from the provider for your request. Token rates apply to `prompt_tokens` and `completion_tokens`, including reported hidden reasoning.
- **Cache reads are discounts.** When accepted usage includes cache hits, the cached share of the prompt is billed at `input_cache_read`, and the saving appears as `cache_discount` in generation metadata.
- **You're charged for output delivered to you.** A request that fails without delivering output costs nothing.

Costs are exact decimal values; parse them as decimals. [`GET /generation`](/docs/api-reference/chat/get-generation) is the authoritative record of what a request cost; see [Usage accounting](/docs/account/usage-accounting).

`provider.max_price` compares against the same listed rates. A USD offer listing `prompt: "0.0000002"` passes `max_price.prompt: 0.0000002`. For a BTC key the same rules apply in sats: a rate of `"0.0005"` is 500 sats per million tokens, which web pages write as `₿500/M`.

## For providers

You propose a public name when you publish; the catalogue binds it to a canonical ID through review, and your own model name stays private to your endpoint. Your listed prices are your earnings rates. See [Pricing for providers](/docs/providers/pricing) and [Review and lifecycle](/docs/providers/lifecycle).

## Next steps

:::cards
- {network} [Provider routing](/docs/routing/provider-routing) Target endpoints by tag, sort and cap prices.
- {shield-check} [Verification and trust](/docs/routing/verification) Why a model or endpoint appears or disappears.
- {branch} [Fallbacks and reliability](/docs/routing/fallbacks) Health, failover and model fallback.
- {receipt} [Usage accounting](/docs/account/usage-accounting) Usage fields and costs.
- {code} [List models reference](/docs/api-reference/models/list-models) Full schema with a live playground.
:::