Embeddings, audio și realtime

Vectori, speech-to-text, text-to-speech, voce realtime peste WebSocket și tokenii efemeri care fac clienții din browser siguri.

Dincolo de chat, gateway-ul servește patru suprafețe media OpenAI-compatibile. Acceptă aceeași cheie, aceleași rate limits și scriu aceleași înregistrări de usage — dar niciuna nu pornește un task facturabil, așa că nu contează niciodată la plafonul de task-uri.

Embeddings

POST /v1/embeddings. Modelul implicit codai-embed se rezolvă la voyage-code-3, ales pentru retrieval de cod. Input-ul este un string sau un array nevid de string-uri; opțional dimensions și user. Se acceptă doar encoding_format: "float".

curl https://ai.codai.ro/v1/embeddings \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "codai-embed", "input": ["salut lume", "vectorizează-mă"] }'

{
  "object": "list",
  "model": "voyage-code-3",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0123, -0.0456, …] },
    { "object": "embedding", "index": 1, "embedding": [0.0789, 0.0012, …] }
  ],
  "usage": { "prompt_tokens": 7, "total_tokens": 7 }
}

Dacă modelul de embedding cerut nu e disponibil, gateway-ul poate servi o alternativă compatibilă și o dezvăluie în x-codai-embed-fallback: <cerut>-><servit>. Verifici header-ul când spațiile vectoriale trebuie să rămână identice între scrieri și citiri.

Speech-to-text

POST /v1/audio/transcriptions, formular multipart, maximum 25 MB. Câmpuri: file (obligatoriu), model (implicit codai-transcribe) și opționalele language, prompt, response_format, temperature — trimise mai departe ca atare.

`model`	Backend
`codai-transcribe`, `whisper-1`, `whisper`	Whisper
`gpt-4o-mini-transcribe`	gpt-4o-mini-transcribe

curl https://ai.codai.ro/v1/audio/transcriptions \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -F [email protected] \
  -F model=codai-transcribe \
  -F language=ro

{ "text": "Să începem cu checklist-ul de deploy." }

Facturarea este fixă per minut de audio, estimată din dimensiunea încărcării (aproximativ 1 MB per minut de voce comprimată, minimum un minut) și înregistrată ca cost_micro_usd pe rândul de usage.

Text-to-speech

POST /v1/audio/speech. Body JSON: input (obligatoriu, ≤ 4 096 caractere), model (implicit codai-tts), voice, response_format (implicit mp3), speed și — doar pentru modelul expresiv — instructions (≤ 1 000 caractere). Body-ul răspunsului sunt byte-ii audio.

`model`	Backend	Voce implicită	Note
`codai-tts`, `tts-1`, `tts`	TTS standard	`alloy`	Ieftin, neutru.
`codai-tts-expressive`, `gpt-4o-mini-tts`	gpt-4o-mini-tts	`marin`	Acceptă `instructions` precum „calm, cald, română scurtă, ușor amuzat”. Voci: alloy, ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse, marin, cedar.

curl https://ai.codai.ro/v1/audio/speech \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "codai-tts", "input": "Salut de la codai.", "voice": "alloy" }' \
  --output salut.mp3

Facturarea este fixă per 1 000 caractere de input.

Tokeni efemeri

Browserele și webview-urile nu trebuie să dețină niciodată cheia ta de lungă durată. În schimb, generezi server-side un token de scurtă durată cu scop limitat cu POST /v1/tokens și îl dai clientului. Scopuri: realtime, audio, embeddings — chat-ul nu poate fi generat intenționat. TTL 60–3 600 s, implicit 600.

curl https://ai.codai.ro/v1/tokens \
  -H "Authorization: Bearer $CODAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "realtime", "ttl_seconds": 600 }'

{ "token": "codai_eph_v1.…", "expires_at": "2026-09-23T12:10:00.000Z", "scope": "realtime" }

Token-ul se folosește exact ca o cheie API — Authorization: Bearer codai_eph_v1.… — dar doar pe suprafața scopului său. Nu poate genera alți tokeni (403 forbidden). Revocarea cheii generatoare sau retrogradarea tier-ului ei invalidează tokenii în circulație în fereastra de cache a principalului.

Voce realtime

WSS /v1/realtime?model=<alias> — audio bidirecțional pe un singur WebSocket, retransmis ca atare către protocolul upstream.

`model`	Protocol	Backend
`codai-realtime` (implicit pentru clienți în stil OpenAI)	OpenAI Realtime	gpt-realtime-2.1
`codai-transcribe-live`	OpenAI Realtime, `intent=transcription`	Doar STT în streaming — parțiale și evenimente de tură, fără răspuns de model
`codai-voice`	Gemini Live `BidiGenerateContent`	gemini-live-2.5-flash-native-audio

Dacă model lipsește, gateway-ul presupune codai-voice.

Autentificarea upgrade-ului

Cheile brute codai_… sunt respinse în query string (cod de închidere 4401). Ar ajunge în log-uri de cereri, proxy-uri și istoricul browserului. Browserele trebuie să folosească un token efemer realtime.

Browser: wss://ai.codai.ro/v1/realtime?model=codai-realtime&key=codai_eph_v1.…
Server: trimiți Authorization: Bearer <cheie sau token> pe cererea de upgrade — ?key= nu mai e necesar.

browser.ts

// token obținut de la backend-ul tău, care a apelat POST /v1/tokens
const ws = new WebSocket(
  `wss://ai.codai.ro/v1/realtime?model=codai-realtime&key=${encodeURIComponent(token)}`,
);
ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'session.update', session: { instructions: 'Răspunde scurt.' } }));
};
ws.onmessage = (ev) => {
  const event = JSON.parse(ev.data);
  if (event.type === 'response.audio.delta') {
    /* adaugi PCM-ul base64 la player */
  }
};

Coduri de închidere pe care le poți vedea: 4401 credențial invalid sau nepermis, 4503 lane-ul cerut nu e configurat pe acest gateway, 1011 eroare internă. Usage-ul se înregistrează la închiderea sesiunii, cu durata ei.