Models

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:

^[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.

• 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 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; 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

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.

Each model page shows the canonical ID, context and output limits, modalities, every routable endpoint with its prices, and 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:

• 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 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

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.

curl "https://api.numes.ai/api/v1/models" \  -H "Authorization: Bearer $NUMES_API_KEY"

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.

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:

curl "https://api.numes.ai/api/v1/models?output_modalities=text&supported_parameters=tools%2Cstructured_outputs&sort=pricing-low-to-high" \  -H "Authorization: Bearer $NUMES_API_KEY"

The model object

{  "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"]      }    }  ]}

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.

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.

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:

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. Sampling controls the chosen offer doesn't declare are dropped unless you set provider.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 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.

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.

List a model's 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.

curl "https://api.numes.ai/api/v1/models/openai/gpt-6-luna/endpoints" \  -H "Authorization: Bearer $NUMES_API_KEY"

{  "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      }    ]  }}

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).

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 is the authoritative record of what a request cost; see 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 and Review and lifecycle.

Next steps