REST API: Voice
Every operation of this group with its parameters, body, answer and errors, as the OpenAPI document states them.
Push-to-talk: the first Talk press, which joins the session's voice room, and the HTTPS fallback that transcribes a recorded question.
Start voice (the first Talk press)
POST/v1/sessions/{id}/voiceViewer token
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The viewer session's id ( |
Request body (application/json)
| Field | Type | Description |
|---|---|---|
addresseeRequired | string | A speaker's or an object's alias, as the documents spell it ( |
beatIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
epochRequired | integer0–9007199254740991 | |
positionRequired | object | WHERE in the story something happened: |
position.visitRequired | integer1–9007199254740991 | |
position.sceneIdRequired | string1–160 characters | An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is |
position.msRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
locale | string≤ 35 characters | A UI or reply language: a BCP 47 tag ( |
Response 200
Start voice (the first Talk press)
| Field | Type | Description |
|---|---|---|
stateRequired | string1–32 characters | One of |
reason | string1–64 characters |
|
aiRequired | object | The session's live-AI status now (the UI hides Talk below |
ai.levelRequired | "off" | "text" | "voice" | |
ai.reasonsRequired | string[] | |
ai.scopesRequired | string[] | |
ai.voiceReplies | string1–32 characters | Added within v1: whether live replies are spoken here — the project's setting, one of |
voiceRequired | object | What the viewer may still say: seconds of voice left today (presses count their pressed time, clips their length) and the longest press the agent takes now (the smaller of |
voice.secondsLeftRequired | integer0–9007199254740991 | |
voice.pressMaxMsRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
connection | object |
|
connection.urlRequired | string1–2048 characters | The LiveKit server, |
connection.tokenRequired | string1–4096 characters | The participant token: join before |
connection.roomRequired | string1–200 characters |
|
connection.identityRequired | string1–200 characters |
|
connection.expiresAtRequired | string (date-time) | An ISO 8601 instant. |
dispatch | string1–32 characters |
|
Errors
400invalid_input401invalid_token,session_expired403scope_required404not_found409stale_epoch429rate_limited503retry_later
Transcribe a recorded question
POST/v1/sessions/{id}/voice/clipsViewer token
The fallback for networks that block WebRTC. The audio is transcribed at once and never stored; at most 8 MB.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
idRequired | path | string | The viewer session's id ( |
locale | query | string | A UI or reply language: a BCP 47 tag ( |
Request body (audio/*)
The raw bytes of the media type.
Response 200
The clip, transcribed. uploadRef names the transcript for ONE viewer_audio turn within a few minutes; it is absent when nothing was heard (transcript empty: "I didn't catch that"). The clip's length counts against the viewer's voice seconds either way.
| Field | Type | Description |
|---|---|---|
uploadRef | string1–200 characters | |
transcriptRequired | string≤ 500 characters | |
durationMsRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
voiceRequired | object | What the viewer may still say: seconds of voice left today (presses count their pressed time, clips their length) and the longest press the agent takes now (the smaller of |
voice.secondsLeftRequired | integer0–9007199254740991 | |
voice.pressMaxMsRequired | integer0–9007199254740991 | A non-negative integer count or time in milliseconds. |
Errors
401invalid_token,session_expired403scope_required,ai_unavailable404not_found413body_too_large415unsupported_media_type429rate_limited503retry_later