Models & usage

Riven exposes a small, stable set of brand model IDs. Behind each ID, Riven routes to the best available backend — including automatic failover — so your integration never chases provider model-name churn.

List the live catalog anytime with GET /v1/models, or fetch names, ordering, and multipliers from GET /v1/catalog?view=tiers (no auth required). The gateway serves 75 live models; per-model pages are in the model fleet.

The Riven tier family — start here#

Seven intent-based tiers cover the full speed/quality range. These are the same lanes shown in the model picker in the Riven apps — the friendly name on the left is what you see there. Pick by what the work needs: riven-best (Riven Auto) when you want Riven to choose; riven-instant when latency matters most; riven-max when quality matters most.

Name	Model ID	Token multiplier	Availability	Description
Riven Auto	`riven-best`	routed lane	All plans	Auto mode — picks the right lane for each message. Usage is billed at whatever lane it routes to. The recommended default in the apps.
Riven Spark	`riven-instant`	1x	All plans	The fastest lane. Sub-second responses for high-volume, latency-sensitive traffic — autocomplete, classification, quick answers.
Riven Bolt	`riven-fast`	1.5x	All plans	Quick everyday chat with strong quality at low cost. A good default for user-facing assistants.
Riven Nova	`riven-core`	3.75x	All plans	The balanced flagship tier — the recommended pinned lane for general workloads and production integrations.
Riven Atlas	`riven-pro`	6.7x	Paid plans	Deep reasoning for hard, multi-step problems. Spends more time thinking; expect higher latency and cost.
Riven Research	`riven-research`	2.3x	Paid plans	Web-grounded research with citations, via Riven Grounding.
Riven Apex	`riven-max`	13.3x	Paid plans	The most capable model Riven offers, with a very large context window. For the hardest work.

Specialty tiers#

Name	Model ID	Token multiplier	Availability	Description
Riven Code	`riven-code`	1x	Paid plans	Code generation, review, and refactoring workloads.
Riven Vision	`riven-vision`	1.25x	Paid plans	Multimodal chat over image inputs.

Requesting a model outside your plan returns HTTP 429 with {"error": {"code": "rate_limit_exceeded", "type": "plan_limit", ...}} and an upgrade pointer — see Errors.

How usage is metered#

Every plan comes with a monthly token allowance. Each request consumes *tokens used × the tier’s token multiplier* from that allowance. A 1,000-token answer on Riven Spark (1x) costs 1,000 allowance tokens; the same answer on Riven Apex (13.3x) costs about 13,300. Riven Auto is billed at whatever lane it routes each message to, so easy messages stay cheap automatically.

Pay-as-you-go keys are metered the same way against a base rate of $3.00 per million tokens: effective price = base rate × tier multiplier. Direct frontier models on pay-as-you-go are billed at vendor list rates instead of multipliers. The accounting is described in Riven Pricing Brain.

Tiers vs. direct frontier models#

The two halves of the catalog carry different stability promises. Tiers are consumer lanes: the name and intent are stable, and Riven may upgrade the backing model behind a lane at any time so it always reflects the best available option. Direct frontier models are the developer contract: exact vendor IDs (for example gpt-5.6 or claude-fable-5) at vendor list pricing, deprecated only with notice. The exact set changes as vendors ship — GET /v1/models is always the source of truth.

Embeddings & image generation#

Model ID	Type	Availability	Description
`riven-embed`	Embeddings	All plans	768-dimension text embeddings for search, clustering, and RAG. Accepts a string or an array of strings.
`riven-embed-fast`	Embeddings	All plans	Same 768-dimension embedding space, tuned for throughput on batch workloads.
`riven-image`	Image generation	All plans	Text-to-image generation. Returns base64-encoded PNG (1024×1024 default) via `POST /v1/images/generations`.

Legacy model IDs#

Earlier integrations used the IDs below. They remain routable so nothing breaks, but they are no longer the recommended targets — each row notes the tier to use for new work.

Model ID	Type	Availability	Description
`riven-ultra`	Chat	All plans	Legacy flagship ID. Still served; new work should target `riven-core`.
`riven-ultra-pro`	Chat / Reasoning	All plans	Legacy capability ID with optional extended-thinking mode (see the note below). New work should target `riven-pro` or `riven-max`.
`riven-ultra-research`	Chat / Research	All plans	Legacy research ID. New work should target `riven-research`.
`riven-chat-sm`	Chat	All plans	Legacy small chat tier. New work should target `riven-instant`.
`riven-chat-md`	Chat	All plans	Legacy mid chat tier. New work should target `riven-fast`.
`riven-chat-lg`	Chat	Paid plans	Legacy large chat tier. New work should target `riven-core`.
`riven-reason`	Reasoning	Paid plans	Legacy reasoning ID. New work should target `riven-pro`.
`riven-agent`	Agents / Tools	All plans	Tuned routing for agentic tool-use loops and function calling.

`riven-ultra-pro` thinking mode: the Pro backend can spend tokens on internal reasoning before answering. With small max_tokens budgets this can consume the entire budget (empty content, finish_reason: "length"). Either allow ≥2000 tokens or disable it per-request.

request body

{"model": "riven-ultra-pro", "chat_template_kwargs": {"enable_thinking": false}, ...}

Listing models#

curl

curl https://api.rivenai.io/v1/models

response (abridged)

{
  "object": "list",
  "data": [
    { "id": "riven-instant", "object": "model", "owned_by": "riven" },
    { "id": "riven-core", "object": "model", "owned_by": "riven" },
    { "id": "riven-max", "object": "model", "owned_by": "riven" }
  ]
}

Responses to completions include the model that actually served the request and an x-riven-upstream header identifying the serving pool, so routed traffic is always attributable. See Riven Ultra Router.

Search docs