Embeddings & Audio

Vector embeddings, speech-to-text, text-to-speech and the ephemeral tokens the realtime WebSocket requires.

Embeddings and audio follow the OpenAI shapes. POST /v1/tokens mints the short-lived token a browser must pass as ?key= when opening wss://ai.codai.ro/v1/realtime — a raw codai_ key in the query string is refused (close code 4401). See the embeddings & audio guide for worked examples.

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

x-codai-session-id?string

Groups requests of one conversation for receipts, stickiness and prompt caching.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

OpenAI-compatible embeddings body. Unknown fields are accepted and ignored.

model?string

Alias or concrete embedding model id. Defaults to codai-embed (platform default voyage-code-3).

Default"codai-embed"

input*|array<string>

One string or a non-empty array of strings. Token-id arrays are not supported.

dimensions?integer

Optional output dimensionality cap. Honoured by OpenAI-style upstreams, ignored by others.

Range1 <= value

user?string

OpenAI tracking field; logged, never forwarded upstream.

encoding_format?"float"

Only float is supported; base64 is rejected with 400.

Value in

"float"

[key: string]?any

Response Body

`application/json`

curl -X POST "https://example.com/v1/embeddings" \  -H "Content-Type: application/json" \  -d '{    "input": "function add(a, b) { return a + b }"  }'

{  "object": "list",  "data": [    {      "object": "embedding",      "index": 0,      "embedding": [        0      ]    }  ],  "model": "voyage-code-3",  "usage": {    "prompt_tokens": 0,    "total_tokens": 0  }}

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

x-codai-session-id?string

Groups requests of one conversation for receipts, stickiness and prompt caching.

Lengthlength <= 128

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

Multipart form fields. Only the listed fields are forwarded; anything else is dropped.

file*file

Audio file, max 25 MB. The original filename is forwarded (audio.webm when absent).

Formatbinary

model?string

codai-transcribe, whisper-1 and whisper map to the Whisper deployment; gpt-4o-mini-transcribe to its own.

Default"codai-transcribe"

Value in

"codai-transcribe"
"whisper-1"
"whisper"
"gpt-4o-mini-transcribe"

language?string

ISO-639-1 language hint, forwarded verbatim.

prompt?string

Optional text to guide style or spelling, forwarded verbatim.

response_format?string

Forwarded verbatim. Use a JSON format (json, verbose_json); text/srt/vtt break the gateway's JSON parse.

Default"json"

temperature?string

Sampling temperature as a string form field (0–1), forwarded verbatim.

Response Body

`application/json`

curl -X POST "https://example.com/v1/audio/transcriptions" \  -F file="string"

{  "text": "Bună, vreau să programez o întâlnire mâine la zece."}

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

x-codai-session-id?string

Groups requests of one conversation for receipts, stickiness and prompt caching.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

model?string

codai-tts/tts-1/tts = neutral voice; codai-tts-expressive/gpt-4o-mini-tts = expressive family that honours instructions.

Default"codai-tts"

Value in

"codai-tts"
"tts-1"
"tts"
"codai-tts-expressive"
"gpt-4o-mini-tts"

input*string

Text to synthesize. Longer than 4096 characters is rejected with 400.

Length1 <= length <= 4096

voice?string

Upstream voice name, not validated. Defaults to alloy (neutral) or marin (expressive). Expressive family also accepts ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse, cedar.

response_format?string

Audio container, forwarded without validation.

Default"mp3"

speed?number

Playback speed multiplier, forwarded when truthy (so 0 is dropped).

instructions?string

Delivery-style hint (e.g. "calm, warm, short Romanian"). Honoured only by the expressive family; truncated to 1000 characters.

Lengthlength <= 1000

Response Body

`application/json`

curl -X POST "https://example.com/v1/audio/speech" \  -H "Content-Type: application/json" \  -d '{    "input": "Bună ziua! Cu ce te pot ajuta astăzi?"  }'

"string"

Authorization

bearerAuth

AuthorizationBearer <token>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by /v1/realtime.

In: header

Header Parameters

x-request-id?string

Client correlation id; echoed back as x-codai-trace-id and persisted on the usage row.

Lengthlength <= 128

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

scope*string

Surface the token may reach. Only realtime, audio and embeddings are accepted; anything else is 400.

Length1 <= length <= 32

ttl_seconds?integer

Lifetime in seconds. Values outside 60–3600 fail validation.

Range60 <= value <= 3600

Default600

Response Body

`application/json`

curl -X POST "https://example.com/v1/tokens" \  -H "Content-Type: application/json" \  -d '{    "scope": "realtime"  }'

{  "token": "codai_eph_v1.eyJraWQiOiIuLi4ifQ.c2lnbmF0dXJl",  "expires_at": "2026-09-23T10:15:00.000Z",  "scope": "realtime"}

200application/json

400application/json

401application/json

402application/json

403application/json

413application/json

429application/json

502application/json

200application/json

400application/json

401application/json

402application/json

403application/json

429application/json

502application/json

200audio/mpeg

400application/json

401application/json

402application/json

403application/json

429application/json

502application/json

200application/json

400application/json

401application/json

402application/json

403application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`