# Modele (/ro/docs/gateway/models)

La ce se rezolvă `codai`, celelalte alias-uri pe care le poți adresa și cum funcționează effort și thinking.

Adresezi gateway-ul prin **alias**, nu prin numele vendorului upstream. Un alias este o identitate stabilă pe care gateway-ul o rezolvă la un model concret în momentul cererii, așa că codul tău nu se schimbă niciodată când se schimbă upstream-ul.

## `codai` — singurul nume de reținut [#codai--singurul-nume-de-reținut]

`model: "codai"` este identitatea principală. Astăzi rutează către modelele Claude actuale ale Anthropic (familiile Opus, Fable, Sonnet și Haiku), cu failover automat între deployment-uri aprobate când unul nu este disponibil. Lanțul din spatele numelui se poate schimba. Header-ul de răspuns `x-codai-routed-to` îți spune care model a răspuns la fiecare cerere, iar [distribuția live a rutării](https://codai.ro/ro#routing) de pe codai.ro arată unde a mers efectiv traficul din producție. Modelele altor furnizori nu fac parte din această rută; le apelezi după nume (vezi [nume upstream directe](#nume-upstream-directe)). Fixează `codai-max` (sau `codai-fable`) când vrei Fable 5.1 primul.

`codai` este și alias-ul cu cea mai multă protecție încorporată:

- **Prompt caching este mereu pornit.** Opt-out-ul `X-Codai-Cache: 0` este ignorat pentru alias-urile `codai*` (este respectat pe numele upstream directe). Citirile din cache costă aproximativ a zecea parte din input-ul proaspăt.
- **Fiecare cerere este contorizată** în micro-USD pe cheia ta, inclusiv sub-apelurile pe care gateway-ul le face în numele tău.
- **Effort este un buton pe care îl controlezi.** API-ul brut pornește implicit pe `medium`; configurația VS Code livrează `high` (`max` e la un pas pe buton). Vezi [effort și thinking](#effort-și-thinking).

<Callout type="info" title="`codai` (automat) sau un model fixat">
| | `codai` | Nume fixat (`codai-fast`, `codai-max`, `claude-sonnet-5-5`, …) |
| --- | --- | --- |
| Cine răspunde | Astăzi, un lanț de modele Claude actuale; câștigă primul deployment sănătos | Mereu acel model (sau failover-ul listat pentru el) |
| Când un deployment pică | Trece la următoarea intrare din lanț | Trece doar în lanțul acelui alias; numele directe nu au failover |
| Cost | Variază cu modelul care a răspuns | Previzibil per model |
| Cum verifici | `x-codai-routed-to`, plus `x-codai-cost-micro-usd` când se știe | Aceleași header-e |

Folosești `codai`, dacă nu ai nevoie de același model la fiecare apel. Numele upstream directe cer un plan care le permite.
</Callout>

<Callout type="info" title="`codai` (automat) sau `codai-1` (beta, fixat)">
| | `codai` | `codai-1-beta` |
| --- | --- | --- |
| Ce este | Numele implicit; astăzi un lanț de modele Claude actuale ale Anthropic, cu failover | Modelul propriu codai, în beta: o versiune DeepSeek-V4.1-Flash (licență MIT) ajustată prin RL, servită de codai |
| Cum îl obții | Orice cheie, orice client | Opt-in: ceri `codai-1-beta` după nume. Nu apare în `GET /v1/models` și nu face niciodată parte din lanțul `codai` |
| Input și unelte | Text, imagini, apeluri de unelte | Doar text; apelurile de unelte sunt oprite în beta |
| Stabilitate | Nume stabil; modelele din spate se pot schimba | Beta: checkpoint-ul din spatele numelui se poate schimba fără notificare, iar disponibilitatea poate fi limitată |
| Cum verifici | `x-codai-routed-to` | Același header |

Folosești `codai` pentru munca reală. Alegi `codai-1-beta` doar ca să încerci modelul propriu codai.
</Callout>

## Alias-uri publice [#alias-uri-publice]

Apar în `GET /v1/models` pentru orice cheie.

| Alias | Servește | Îl folosești pentru |
| --- | --- | --- |
| `codai` | Astăzi, modelele Claude actuale ale Anthropic, cu failover automat (modelul care a răspuns apare în `x-codai-routed-to`) | Orice. Implicitul. |
| `codai-labs` | Aceeași rutare ca `codai` astăzi, plus funcții de cercetare de frontieră pe măsură ce apar (răspunsuri de cod verificate prin execuție, best-of-N ordonat prin execuție, modele open-weight noi) | Să încerci ce urmează. Comportamentul se poate schimba fără notificare — fixează `codai` pentru stabilitate. |

## Alias-uri de workload [#alias-uri-de-workload]

Ascunse din listarea `/v1/models`, dar rezolvabile de orice cheie care poate adresa `codai`. Există ca integrările IDE să poată fixa un rol pe un model fără să inventeze nume proprii.

| Alias | Servește | Note |
| --- | --- | --- |
| `codai-fast` | Claude Haiku 5.5 (failover: Haiku 4.5) | Muncă utilitară: titluri, detecție de intenție, mesaje de commit. Fără sarcină când e trimis cu `X-Codai-No-Task: 1`. |
| `codai-explorer` | Claude Sonnet 5.5 (failover: Sonnet 5) | Citire și căutare în codebase — multe ture scurte în care latența bate deliberarea. |
| `codai-agent` | La fel ca `codai` | Implementare cu multe unelte. |
| `codai-deep` | La fel ca `codai` | Raționament profund. |
| `codai-max` | Claude Fable 5.1 (failover: Opus 5.5) | Pin de escaladare: raționament greu, orizont lung. |
| `codai-vision` | La fel ca `codai` | Input de imagini activat. |
| `codai-smart` | Claude Sonnet 5 | Tier echilibrat. |
| `codai-opus` | Claude Opus 5.5 | Fixare explicită pe clasa Opus. |
| `codai-flash` | Gemini 2.5 Flash | Multimodal ieftin. |
| `codai-latest` | La fel ca `codai` | Nume vechi păstrat pentru configurații existente. |

<Callout type="info">
`codai-agent`, `codai-deep` și `codai-vision` au astăzi același chain ca `codai`; `codai-max` e cel care pornește cu Fable 5.1. [Butonul de effort](#effort-și-thinking) acoperă ce distingeau acestea înainte, motiv pentru care picker-ul din VS Code publică acum doar `codai`, `codai-fast` și `codai-explorer`.
</Callout>

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

`codai-max-n` este un mod opțional pentru sarcini grele, distinct de pinul `codai-max`. E oprit până când operatorul gateway-ului îl pornește; cât timp e oprit, numele e respins ca orice model necunoscut (HTTP 400). Nu apare niciodată în `/v1/models` și poate fi adresat de orice cheie care poate adresa `codai`.

Pentru fiecare cerere, gateway-ul:

1. generează în paralel mai multe răspunsuri candidate (implicit 4, maximum 8);
2. elimină candidații defecți și, când codul poate rula în sandbox, îi preferă pe cei al căror cod chiar rulează;
3. cere **unui singur** judecător să compare deodată toți candidații rămași și să aleagă unul, cu un scor de încredere;
4. când judecătorul e nesigur, întreabă o singură dată un model frontier și servește acel răspuns. Un răspuns verificat prin execuție nu este escaladat niciodată.

| Header de răspuns | Semnificație |
| --- | --- |
| `x-codai-max-n` | Numărul de candidați ceruți |
| `x-codai-max-escalated` | `1` când a răspuns reîntrebarea frontier |
| `x-codai-max-method` | `judge`, `exec`, `deterministic`, `escalated` sau `single` |
| `x-codai-routed-to` | Modelul care a produs răspunsul servit |
| `x-codai-cost-micro-usd` | Suma tuturor apelurilor: candidați, judecător și escaladare |

<Callout type="warn" title="Cost și latență">
O cerere costă aproximativ cât N + 1 până la N + 2 apeluri simple, iar fiecare apel e contorizat pe cheia ta. Răspunsurile sunt bufferizate: cu `stream: true` nu se trimite nimic până la final, apoi răspunsul ales sosește ca o singură secvență în flux. Primul byte vine după cel mai lent candidat plus judecător. Folosește-l pentru probleme grele, de sine stătătoare, nu pentru bucle de agent.
</Callout>

## Alias-uri cu scop special [#alias-uri-cu-scop-special]

| Alias | Suprafață | Servește |
| --- | --- | --- |
| `codai-embed` | `POST /v1/embeddings` | voyage-code-3 |
| `codai-transcribe` | `POST /v1/audio/transcriptions` | Whisper |
| `codai-tts` | `POST /v1/audio/speech` | Voce TTS neutră (`alloy` implicit) |
| `codai-tts-expressive` | `POST /v1/audio/speech` | gpt-4o-mini-tts — acceptă `instructions` | {/* model-claims-allow: audio alias table, not the chat catalog */}
| `codai-speech` | `POST /v1/audio/speech` | Google Chirp 3 HD — 30 de voci native în română (`Aoede` implicit), rapid |
| `codai-speech-expressive` | `POST /v1/audio/speech` | Gemini 2.5 Flash TTS — română nativă, acceptă `instructions` | {/* model-claims-allow: audio alias table, not the chat catalog */}
| `codai-tts-ro` | `POST /v1/audio/speech/stream` | Voci neurale Azure (ro-RO Alina / Emil) transmise în streaming cu viseme și momentele cuvintelor |
| `codai-music` | `POST /v1/audio/music` | Lyria 3 Clip — 30 s cu voce și versuri |
| `codai-music-pro` | `POST /v1/audio/music` | Lyria 3 Pro — piesă întreagă de până la 184 s cu voce, versuri, `bpm` |
| `codai-music-legacy` | `POST /v1/audio/music` | Lyria 2 — WAV instrumental de 30 s |
| `codai-sfx` | `GET /v1/studio/sfx` | Biblioteca de efecte sonore Studio — sunete CC0 selectate + completare CC0 din Freesound, gratuit ([detalii](./sfx.mdx)) |
| `codai-realtime` | `WSS /v1/realtime` | gpt-realtime-2.1 (protocol OpenAI Realtime) |
| `codai-transcribe-live` | `WSS /v1/realtime` | Doar STT în streaming, fără răspuns de model; `?language=ro` rulează pe Deepgram Nova-3 când e configurat |
| `codai-voice` | `WSS /v1/realtime` | Gemini Live audio nativ (protocol Gemini Live) |

Detalii și exemple pe pagina [embeddings, audio și realtime](./embeddings-audio.mdx).

## Nume upstream directe [#nume-upstream-directe]

Poți ocoli alias-urile și numi un model concret — `claude-sonnet-5-5`, `gpt-6.1-sol`, `gemini-3.8-flash`, `grok-4.6` și așa mai departe — dacă planul tău îl permite. `GET /v1/models` returnează exact ce poate adresa cheia ta, alias-uri și modele concrete la fel:

```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 }
      }
    }
  ]
}
```

Obiectul `codai` este o extensie non-standard; clienții OpenAI-compatibili îl ignoră, IDE-urile îl citesc pentru a-și dimensiona indicatorii de context. `owned_by` este `codai` pentru alias-uri și `codai-upstream` pentru modele concrete.

## Catalogul public [#catalogul-public]

`GET /v1/public/models` nu cere cheie. Întoarce lista curatoriată a modelelor pe care codai le numește public, filtrată după ce rutează gateway-ul **chiar acum**: un model scos din rutare dispare din răspuns în câteva minute. Include și modelele open-weight proprii codai, care rulează pe dispozitivul tău și nu trec niciodată prin gateway. CORS este deschis (`*`), iar răspunsurile pot fi păstrate în cache o oră, așa că site-urile îl pot citi direct.

```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). …" }
  ]
}
```

Textele `description` și `note` sunt în engleză.

| Câmp | Semnificație |
| --- | --- |
| `live` | `false` când gateway-ul nu și-a putut citi tabela de rutare; `data` este atunci lista curatoriată completă, iar răspunsul se păstrează în cache doar 5 minute. |
| `aliases[].routesTo` | Lanțul live al fiecărui alias public, fără duplicatele de lane. |
| `data[].aliases` | Alias-urile publice care pot ruta către model. O listă goală înseamnă că îl apelezi după nume, pe planurile care îl permit. |
| `data[].tier` | `small`, `medium`, `large` sau `frontier`. |
| `data[].preview` | `true` cât timp furnizorul încă marchează modelul ca preview. |
| `data[].own`, `base`, `note` | Modelele proprii codai: modelul de bază open-weight și unde rulează. |

Dacă cheia ta poate apela un model decide `GET /v1/models`, nu această listă.

## Cum funcționează rezolvarea [#cum-funcționează-rezolvarea]

Fiecare alias poartă un **lanț** de intrări `{ provider, upstreamModel }`. La fiecare cerere gateway-ul parcurge lanțul, sare adaptoarele marcate momentan ca nesănătoase și trimite către primul sănătos. Lanțul este dată, reîncărcată din registru la fiecare minut — adăugarea sau schimbarea unui upstream nu modifică niciun cod de client. Allowlist-ul cheii tale (dacă tier-ul setează unul) se aplică modelului rezolvat, nu alias-ului, așa că un tier care permite `codai` permite și `codai-fast`.

## Effort și thinking [#effort-și-thinking]

Adâncimea raționamentului este un **buton**, nu un model. O setezi per cerere în oricare dintre două moduri echivalente:

<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": "Demonstrează că √2 este irațional." }] }'
```

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

```json
{
  "model": "codai",
  "reasoning_effort": "high",
  "messages": [{ "role": "user", "content": "Demonstrează că √2 este irațional." }]
}
```

</Tab>
</Tabs>

Header-ul câștigă când sunt prezente ambele. Când nu e setat niciunul, gateway-ul folosește `medium`. Tier-urile, de la cel mai ieftin la cel mai scump:

| Tier | Buget de thinking | Când |
| --- | --- | --- |
| `minimal` | niciunul | Căutări, formatare, clasificare. |
| `low` | 4 096 tokeni | Editări mici. |
| `medium` | 8 192 tokeni | Implicitul. Cod și scris de zi cu zi. |
| `high` | 16 384 tokeni | Bug-uri grele, întrebări de design. |
| `max` | 32 768 tokeni | Demonstrații, planuri lungi în mai mulți pași. `max` este o extensie codai peste vocabularul OpenAI `low`/`medium`/`high`; Responses API mapează `xhigh` la el. |

Poți activa și extended thinking direct: `X-Codai-Thinking: 1` îl pornește, `X-Codai-Thinking-Budget: <tokeni>` setează bugetul (implicit 16 384).

### Atenuarea pe continuări [#atenuarea-pe-continuări]

Într-o buclă de agent, majoritatea turelor sunt modelul consumând un rezultat de unealtă, nu pornind o sarcină. Pe aceste **ture de continuare cu unelte** gateway-ul limitează orice buget de thinking injectat la 4 096 tokeni, ca o buclă de 30 de pași să nu plătească factura `max` de 30 de ori. Turele proaspete de utilizator păstrează bugetul complet.

Dacă ai nevoie de bugetul complet la fiecare pas — o demonstrație lungă purtată peste apeluri de tool, de exemplu — trimiți `X-Codai-Thinking-Pin: 1`. Header-ul de răspuns `x-codai-effort-continuation-dampened: 1` îți spune când s-a aplicat limitarea.

### Ce îți spune răspunsul [#ce-îți-spune-răspunsul]

| Header | Semnificație |
| --- | --- |
| `x-codai-effort` | Tier-ul de effort pe care l-a rezolvat gateway-ul. |
| `x-codai-effort-applied` | `true` când tier-ul a schimbat apelul upstream; `false` când modelul nu acceptă un parametru de effort. |
| `x-codai-effort-continuation-dampened` | `1` când s-a aplicat limitarea pe continuare. |
| `x-codai-routed-to` | Modelul upstream concret. |