Models

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

model: "codai" is the primary identity. Today it serves Claude Opus 5.5, with Claude Fable 5.1 as the escalation/failover lane (then Opus 5). It fails over between approved deployments and, only when every Opus 5.5 lane is down, sideways to Fable — x-codai-routed-to tells you which model served every request. 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.

Public aliases

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

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.

Special-purpose aliases

Details and examples are on the embeddings, audio & realtime page.

Direct upstream names

You can bypass aliases and name a concrete model — claude-sonnet-4-6, gpt-5, gemini-2.5-pro and so on. GET /v1/models returns exactly what your key may address, aliases and concrete models alike:

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

{
  "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"],
        "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.

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

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

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." }] }'

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

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

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