# Models (/docs/gateway/models)

What `codai` resolves to, the other aliases you can address, and how effort and thinking work.

You address the gateway by **alias**, not by upstream vendor name. An alias is a stable identity that the gateway resolves to a concrete model at request time, so your code never changes when the upstream does.

## `codai` — the one name to remember [#codai--the-one-name-to-remember]

`model: "codai"` is the primary identity. Today it routes to Anthropic's current Claude models (the Opus, Fable, Sonnet and Haiku families), with automatic failover between approved deployments when one is unavailable. The chain behind the name can change. The `x-codai-routed-to` response header tells you which model served every request, and the [live routing distribution](https://codai.ro/#routing) on codai.ro shows where production traffic actually went. Models from other providers are not in this route; address them by name (see [direct upstream names](#direct-upstream-names)). Pin `codai-max` (or `codai-fable`) when you want Fable 5.1 first.

`codai` is also the alias with the most protection built in:

- **Prompt caching is always on.** The `X-Codai-Cache: 0` opt-out is ignored for `codai*` aliases (it is honoured on direct upstream names). Cache reads cost roughly a tenth of fresh input.
- **Every request is metered** in micro-USD against your key, including any sub-calls the gateway makes on your behalf.
- **Effort is a dial you control.** The raw API defaults to `medium`; the VS Code config ships `high` (`max` is one dial step away). See [effort and thinking](#effort-and-thinking).

<Callout type="info" title="`codai` (auto) or a pinned model">
| | `codai` | Pinned name (`codai-fast`, `codai-max`, `claude-sonnet-5-5`, …) |
| --- | --- | --- |
| What answers | Today, a chain of current Claude models; the first healthy deployment wins | Always that model (or its own listed failover) |
| When a deployment is down | Fails over to the next entry in the chain | Fails over only within that alias's chain; direct names have none |
| Cost | Varies with the model that answered | Predictable per model |
| How to check | `x-codai-routed-to`, plus `x-codai-cost-micro-usd` when known | Same headers |

Use `codai` unless you need the same model on every call. Direct upstream names need a plan that allows them.
</Callout>

<Callout type="info" title="`codai` (auto) or `codai-1` (beta, pinned)">
| | `codai` | `codai-1-beta` |
| --- | --- | --- |
| What it is | The default name; today a chain of Anthropic's current Claude models with failover | codai's own model, in beta: an RL fine-tune of DeepSeek-V4.1-Flash (MIT licence), served by codai |
| How you get it | Any key, every client | Opt-in: ask for `codai-1-beta` by name. It is not listed in `GET /v1/models` and is never part of the `codai` chain |
| Input and tools | Text, images, tool calling | Text only; tool calling is off during the beta |
| Stability | Stable name; the models behind it can change | Beta: the checkpoint behind the name can change without notice, and availability can be limited |
| How to check | `x-codai-routed-to` | Same header |

Use `codai` for real work. Pick `codai-1-beta` only to try codai's own model.
</Callout>

## Public aliases [#public-aliases]

These appear in `GET /v1/models` for every key.

| Alias | Serves | Use it for |
| --- | --- | --- |
| `codai` | Today, Anthropic's current Claude models, with automatic failover (the served model is in `x-codai-routed-to`) | Everything. The default. |
| `codai-labs` | Same routing as `codai` today, plus frontier-research features as they land (execution-verified code answers, exec-ranked best-of-N, new open-weight models) | Trying what is next. Behaviour may change without notice — pin `codai` for stability. |

## Workload aliases [#workload-aliases]

Hidden from `/v1/models` listings but resolvable by any key that can address `codai`. They exist so IDE integrations can pin a role to a model without inventing their own names.

| Alias | Serves | Notes |
| --- | --- | --- |
| `codai-fast` | Claude Haiku 5.5 (failover: Haiku 4.5) | Utility work: titles, intent detection, commit messages. Task-free when sent with `X-Codai-No-Task: 1`. |
| `codai-explorer` | Claude Sonnet 5.5 (failover: Sonnet 5) | Codebase reading and search — many short turns where latency beats deliberation. |
| `codai-agent` | Same as `codai` | Tool-heavy implementation. |
| `codai-deep` | Same as `codai` | Deep reasoning. |
| `codai-max` | Claude Fable 5.1 (failover: Opus 5.5) | Escalation pin: demanding, long-horizon reasoning. |
| `codai-vision` | Same as `codai` | Image input enabled. |
| `codai-smart` | Claude Sonnet 5 | Balanced tier. |
| `codai-opus` | Claude Opus 5.5 | Explicit Opus-class pin. |
| `codai-flash` | Gemini 2.5 Flash | Cheap multimodal. |
| `codai-latest` | Same as `codai` | Legacy name kept for old configs. |

<Callout type="info">
`codai-agent`, `codai-deep` and `codai-vision` all share `codai`'s chain today; `codai-max` is the one that leads with Fable 5.1. The [effort dial](#effort-and-thinking) covers what these used to distinguish, which is why the VS Code picker now publishes only `codai`, `codai-fast` and `codai-explorer`.
</Callout>

## codai Max (preview) [#codai-max-preview]

`codai-max-n` is an opt-in hard-task mode, separate from the `codai-max` pin. It is off unless the gateway operator enables it; while it is off the name is rejected like any unknown model (HTTP 400). It is never listed in `/v1/models` and is addressable by any key that can address `codai`.

For each request the gateway:

1. generates several candidate answers in parallel (4 by default, at most 8);
2. drops broken candidates and, when code can be executed in the sandbox, prefers the candidates whose code actually runs;
3. asks **one** judge to compare all remaining candidates at once and pick one, with a confidence score;
4. when the judge is unsure, re-asks a frontier model once and serves that answer. An execution-verified answer is never escalated.

| Response header | Meaning |
| --- | --- |
| `x-codai-max-n` | Candidates requested |
| `x-codai-max-escalated` | `1` when the frontier re-ask answered |
| `x-codai-max-method` | `judge`, `exec`, `deterministic`, `escalated` or `single` |
| `x-codai-routed-to` | Model that produced the served answer |
| `x-codai-cost-micro-usd` | Sum of every candidate, judge and escalation call |

<Callout type="warn" title="Cost and latency">
One request costs roughly N + 1 to N + 2 single calls, and every call is metered on your key. Answers are buffered: with `stream: true` nothing is sent until selection finishes, then the chosen answer arrives as one streamed sequence. Expect the first byte after the slowest candidate plus the judge. Use it for hard, self-contained problems, not for agent loops.
</Callout>

## Special-purpose aliases [#special-purpose-aliases]

| Alias | Surface | Serves |
| --- | --- | --- |
| `codai-embed` | `POST /v1/embeddings` | voyage-code-3 |
| `codai-transcribe` | `POST /v1/audio/transcriptions` | Whisper |
| `codai-tts` | `POST /v1/audio/speech` | Neutral TTS voice (`alloy` default) |
| `codai-tts-expressive` | `POST /v1/audio/speech` | gpt-4o-mini-tts — takes `instructions` | {/* model-claims-allow: audio alias table, not the chat catalog */}
| `codai-speech` | `POST /v1/audio/speech` | Google Chirp 3 HD — 30 native Romanian voices (`Aoede` default), fast |
| `codai-speech-expressive` | `POST /v1/audio/speech` | Gemini 2.5 Flash TTS — native Romanian, takes `instructions` | {/* model-claims-allow: audio alias table, not the chat catalog */}
| `codai-tts-ro` | `POST /v1/audio/speech/stream` | Azure neural voices (ro-RO Alina / Emil) streamed with visemes and word timing |
| `codai-music` | `POST /v1/audio/music` | Lyria 3 Clip — 30 s with vocals and lyrics |
| `codai-music-pro` | `POST /v1/audio/music` | Lyria 3 Pro — full song up to 184 s with vocals, lyrics, `bpm` |
| `codai-music-legacy` | `POST /v1/audio/music` | Lyria 2 — 30 s instrumental WAV |
| `codai-sfx` | `GET /v1/studio/sfx` | Studio sound-effects library — curated CC0 sounds + Freesound CC0 fallback, free ([details](./sfx.mdx)) |
| `codai-realtime` | `WSS /v1/realtime` | gpt-realtime-2.1 (OpenAI Realtime protocol) |
| `codai-transcribe-live` | `WSS /v1/realtime` | Streaming STT only, no model reply; `?language=ro` runs on Deepgram Nova-3 when configured |
| `codai-voice` | `WSS /v1/realtime` | Gemini Live native audio (Gemini Live protocol) |

Details and examples are on the [embeddings, audio & realtime](./embeddings-audio.mdx) page.

## Direct upstream names [#direct-upstream-names]

You can bypass aliases and name a concrete model — `claude-sonnet-5-5`, `gpt-6.1-sol`, `gemini-3.8-flash`, `grok-4.6` and so on — when your plan allows it. `GET /v1/models` returns exactly what your key may address, aliases and concrete models alike:

```bash
curl https://ai.codai.ro/v1/models -H "Authorization: Bearer $CODAI_API_KEY"
```

```json
{
  "object": "list",
  "data": [
    {
      "id": "codai",
      "object": "model",
      "created": 0,
      "owned_by": "codai",
      "codai": {
        "kind": "alias",
        "type": "chat",
        "routesTo": ["claude-opus-5-5", "claude-fable-5-1", "claude-opus-5", "claude-sonnet-5-5", "claude-sonnet-5", "claude-haiku-5-5", "claude-haiku-4-5"],
        "capabilities": { "tools": true, "vision": true, "streaming": true, "maxInputTokens": 1000000, "maxOutputTokens": 128000 }
      }
    }
  ]
}
```

The `codai` object is a non-standard extension; OpenAI-compatible clients ignore it, IDEs read it to size their context indicators. `owned_by` is `codai` for aliases and `codai-upstream` for concrete models.

## Public catalog [#public-catalog]

`GET /v1/public/models` needs no key. It returns the curated list of models codai names publicly, filtered by what the gateway routes **right now**: a model that is dropped from routing disappears from the response within minutes. It also lists codai's own open-weight models, which run on your device and are never routed by the gateway. CORS is open (`*`) and responses are cacheable for an hour, so websites can read it directly.

```bash
curl https://ai.codai.ro/v1/public/models
```

```json
{
  "object": "list",
  "updated": "2026-10-11T12:00:00.000Z",
  "live": true,
  "aliases": [
    { "id": "codai", "description": "The default. Routes each request across Anthropic's current Claude models by task tier: …", "routesTo": ["claude-opus-5-5", "claude-fable-5-1", "claude-sonnet-5-5", "claude-haiku-5-5"] },
    { "id": "codai-fast", "description": "…", "routesTo": ["claude-haiku-5-5", "claude-haiku-4-5"] }
  ],
  "data": [
    { "id": "claude-opus-5-5", "name": "Claude Opus 5.5", "provider": "Anthropic", "family": "Claude Opus", "via": ["Google Vertex AI", "Microsoft Azure AI Foundry"], "tier": "large", "kind": "chat", "released": "2026-09-22", "own": false, "highlight": true, "aliases": ["codai"] },
    { "id": "gpt-6.1-sol", "name": "GPT-6.1 Sol", "provider": "OpenAI", "family": "GPT-6", "via": ["Microsoft Azure AI Foundry"], "tier": "large", "kind": "chat", "own": false, "highlight": true, "aliases": [] },
    { "id": "codai-nano", "name": "codai-nano", "provider": "codai", "family": "codai-nano", "via": ["on-device"], "tier": "small", "kind": "chat", "own": true, "highlight": true, "aliases": [], "base": "google/gemma-4-E2B-it", "note": "Runs on your Android phone in the codai app (LiteRT-LM). …" }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `live` | `false` when the gateway could not read its routing table; `data` is then the full curated list and the response is cached for 5 minutes only. |
| `aliases[].routesTo` | The live chain of each public alias, lane duplicates removed. |
| `data[].aliases` | Which public aliases can route to the model. An empty list means you reach it by name, on plans that allow it. |
| `data[].tier` | `small`, `medium`, `large` or `frontier`. |
| `data[].preview` | `true` while the upstream still labels the model preview. |
| `data[].own`, `base`, `note` | codai's own models: open-weight base and where it runs. |

Whether your key may call a model is decided by `GET /v1/models`, not by this list.

## How resolution works [#how-resolution-works]

Each alias carries a **chain** of `{ provider, upstreamModel }` entries. On every request the gateway walks the chain, skips adapters currently marked unhealthy, and dispatches to the first healthy one. The chain is data, refreshed from the registry every minute — adding or swapping an upstream changes no client code. Your key's allowlist (if the tier sets one) is applied to the resolved model, not the alias, so a tier that allows `codai` also allows `codai-fast`.

## Effort and thinking [#effort-and-thinking]

Reasoning depth is a **dial**, not a model. Set it per request in either of two equivalent ways:

<Tabs items={['Header', 'Body']}>
<Tab value="Header">

```bash
curl https://ai.codai.ro/v1/chat/completions \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Codai-Effort: high" \
  -d '{ "model": "codai", "messages": [{ "role": "user", "content": "Prove that √2 is irrational." }] }'
```

</Tab>
<Tab value="Body">

```json
{
  "model": "codai",
  "reasoning_effort": "high",
  "messages": [{ "role": "user", "content": "Prove that √2 is irrational." }]
}
```

</Tab>
</Tabs>

The header wins when both are present. When neither is set, the gateway uses `medium`. Tiers, from cheapest to most expensive:

| Tier | Thinking budget | When |
| --- | --- | --- |
| `minimal` | none | Lookups, formatting, classification. |
| `low` | 4 096 tokens | Small edits. |
| `medium` | 8 192 tokens | The default. Everyday coding and writing. |
| `high` | 16 384 tokens | Hard bugs, design questions. |
| `max` | 32 768 tokens | Proofs, long multi-step plans. `max` is a codai extension over OpenAI's `low`/`medium`/`high`; the Responses API maps `xhigh` to it. |

You can also enable extended thinking directly: `X-Codai-Thinking: 1` turns it on, `X-Codai-Thinking-Budget: <tokens>` sets the budget (default 16 384).

### Continuation dampening [#continuation-dampening]

In an agent loop, most turns are the model consuming a tool result rather than starting a task. On those **tool-continuation turns** the gateway clamps any injected thinking budget to 4 096 tokens so a 30-step loop does not pay the full `max` bill 30 times. Fresh user turns keep the full budget.

If you need the full budget on every step — a long proof carried across tool calls, for instance — send `X-Codai-Thinking-Pin: 1`. The response header `x-codai-effort-continuation-dampened: 1` tells you when the clamp fired.

### What the response tells you [#what-the-response-tells-you]

| Header | Meaning |
| --- | --- |
| `x-codai-effort` | The effort tier the gateway resolved. |
| `x-codai-effort-applied` | `true` when the tier changed the upstream call; `false` when the model does not take an effort parameter. |
| `x-codai-effort-continuation-dampened` | `1` when the continuation clamp applied. |
| `x-codai-routed-to` | The concrete upstream model. |