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.

POST

/v1/embeddings

Authorization

bearerAuth

headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

Request Body

application/json

body

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

Embedding vectors in OpenAI list shape.

application/json

response

object*"list"

Value in"list"

data*array<>

model*string

Upstream model that produced the vectors (matches x-codai-routed-to).

usage*

Example Request

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

Example Request

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

Example ResponseSchema

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

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

POST

/v1/audio/transcriptions

Authorization

bearerAuth

headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

Request Body

multipart/form-data

body

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

The transcription as returned by the upstream deployment.

application/json

response

The upstream JSON is returned unchanged. With verbose_json extra fields (language, duration, segments, …) appear alongside text.

text?string

The transcript.

[key: string]?any

Example Request

curl -X POST 'https://ai.codai.ro/v1/audio/transcriptions' \
  -F 'file=string'

Example Request

curl -X POST 'https://ai.codai.ro/v1/audio/transcriptions' \  -F 'file=string'

Example ResponseSchema

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

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

POST

/v1/audio/speech

Authorization

bearerAuth

headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

Request Body

application/json

body

model?string

codai-tts/tts-1/tts = neutral voice; codai-tts-expressive/gpt-4o-mini-tts = expressive family that honours instructions; codai-speech = Chirp 3 HD (native Romanian, fast); codai-speech-expressive = Gemini 2.5 Flash TTS (native Romanian, honours instructions).

Default"codai-tts"

Value in"codai-tts""tts-1""tts""codai-tts-expressive""gpt-4o-mini-tts""codai-speech""codai-speech-expressive"

input*string

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

Length1 <= length <= 4096

voice?string

Voice name, not validated. Defaults to alloy (neutral), marin (expressive), Aoede (codai-speech) or Kore (codai-speech-expressive). The expressive family also accepts ash, ballad, coral, echo, fable, onyx, nova, sage, shimmer, verse, cedar. The codai-speech models accept the 30 Chirp 3 HD short names (Achernar … Zubenelgenubi) or a full Google voice name.

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, slow"). Honoured only by codai-tts-expressive/gpt-4o-mini-tts and codai-speech-expressive; truncated to 1000 characters.

Lengthlength <= 1000

language?string

BCP-47 language of the text. Selects the voice locale for the codai-speech models and hints the word-timing transcription.

Default"ro-RO"

timestamps?boolean

Return per-word timings in words. Switches the response to SpeechJson.

Defaultfalse

store?boolean

Store the audio as a studio asset (kind speech, with words in its metadata when timestamps is set) and return it as asset instead of b64_json. Switches the response to SpeechJson.

Defaultfalse

Response Body

Binary audio in the requested format (the media type is whatever the upstream returned, audio/mpeg when it sent none), or SpeechJson when timestamps or store is true.

response

Returned by POST /v1/audio/speech when timestamps or store is true.

object*"audio.speech"

Value in"audio.speech"

model*string

The public model id that served the request.

voice*string

language*string

mime_type*string

duration_seconds*number

Length of the audio in seconds.

b64_json?string

Base64 audio. Present when store is not true.

asset?

A codai Studio asset. Returned by /v1/assets and, with response_format: "url", in the data of the image, music and video endpoints.

words?array<>|

Per-word timings; present only when timestamps was true, null when the timing pass failed.

cost_micro_usd*string

Upstream cost of the request in micro-USD, as a decimal string.

Example Request

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

Example Request

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

Example ResponseSchema

{
  "object": "audio.speech",
  "model": "codai-speech",
  "voice": "Aoede",
  "language": "ro-RO",
  "mime_type": "audio/mpeg",
  "duration_seconds": 0,
  "b64_json": "string",
  "asset": {
    "asset_id": "b4695157-0d1d-4da0-8f9e-5c53149389e4",
    "kind": "music",
    "status": "pending",
    "model": "lyria-002",
    "url": "http://example.com",
    "mime_type": "audio/wav",
    "bytes": 0,
    "duration_seconds": 0,
    "width": 0,
    "height": 0,
    "created_at": "2019-08-24T14:15:22Z",
    "expires_at": "2019-08-24T14:15:22Z"
  },
  "words": [
    {
      "word": "Bună",
      "start": 0,
      "end": 0
    }
  ],
  "cost_micro_usd": "480"
}

{  "object": "audio.speech",  "model": "codai-speech",  "voice": "Aoede",  "language": "ro-RO",  "mime_type": "audio/mpeg",  "duration_seconds": 0,  "b64_json": "string",  "asset": {    "asset_id": "b4695157-0d1d-4da0-8f9e-5c53149389e4",    "kind": "music",    "status": "pending",    "model": "lyria-002",    "url": "http://example.com",    "mime_type": "audio/wav",    "bytes": 0,    "duration_seconds": 0,    "width": 0,    "height": 0,    "created_at": "2019-08-24T14:15:22Z",    "expires_at": "2019-08-24T14:15:22Z"  },  "words": [    {      "word": "Bună",      "start": 0,      "end": 0    }  ],  "cost_micro_usd": "480"}

POST

/v1/tokens

Authorization

bearerAuth

headerAuthorizationBearer <codai_…>

A codai API key (codai_ prefix). Ephemeral tokens from POST /v1/tokens are accepted only by the media surfaces matching their scope (/v1/realtime, /v1/audio/*, /v1/embeddings).

Header Parameters

Request Body

application/json

body

scope*string

Surface the token may reach. Only realtime, audio, embeddings and live (realtime + audio) 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

The minted token, its expiry and the scope it was bound to.

application/json

response

token*string

Bearer credential of the form codai_eph_v1.<payload>.<signature>. Pass it as Authorization: Bearer or as ?key= on /v1/realtime.

expires_at*string

Expiry as an ISO-8601 timestamp.

Formatdate-time

scope*string

Value in"realtime""audio""embeddings""live"

Example Request

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

Example Request

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

Example ResponseSchema

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

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

Embeddings & Audio

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

AuthorizationCopy Anchor Link

Header ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Header Parameters

Request Body

Response Body

Authorization

Header Parameters

Request Body

Response Body

Authorization

Header Parameters

Request Body

Response Body

Authorization

Header Parameters

Request Body

Response Body