Skip to content
Jami3D
Developer docs menu

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

NameInTypeDescription
idRequiredpathstring

The viewer session's id (session.id in the mint answer).

Request body (application/json)

FieldTypeDescription
addresseeRequiredstring

A speaker's or an object's alias, as the documents spell it (teacher_mouse, cat_book).

beatIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

epochRequiredinteger0–9007199254740991
positionRequiredobject

WHERE in the story something happened: visit starts at 1 and grows only under navigationHistory: keep; sceneId names a scene of the session's release (the server maps it to the scene's index and compares anchors lexicographically as (visit, sceneIndex, ms)); ms is authored scene time — a fact recorded during a hold carries the hold's time.

position.visitRequiredinteger1–9007199254740991
position.sceneIdRequiredstring1–160 characters

An id from the project's documents: a scene, a Beat (an interactive scene's synthetic Beat is scene:{sceneId}), an entity, a behaviour, a rule, a variable, a quiz, a question, a choice.

position.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

localestring≤ 35 characters

A UI or reply language: a BCP 47 tag (en, pt-BR, zh-Hant-TW).

Response 200

Start voice (the first Talk press)

FieldTypeDescription
stateRequiredstring1–32 characters

One of V1_VOICE_STATES.

reasonstring1–64 characters

refused: one of V1_VOICE_REFUSED_REASONS.

aiRequiredobject

The session's live-AI status now (the UI hides Talk below voice).

ai.levelRequired"off" | "text" | "voice"
ai.reasonsRequiredstring[]
ai.scopesRequiredstring[]
ai.voiceRepliesstring1–32 characters

Added within v1: whether live replies are spoken here — the project's setting, one of V1_VOICE_REPLIES (open: a value a reader does not know reads as absent). Changing it moves the AI watch's stamp. Absent: this answer does not say (a server from before, an answer that reads the session alone — the events answer); keep what an earlier answer said, and with none, ask for spoken replies as before (output.audio true when audio can play).

voiceRequiredobject

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 V1_VOICE_LIMITS pressMaxMs and what is left).

voice.secondsLeftRequiredinteger0–9007199254740991
voice.pressMaxMsRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

connectionobject

ready: the room to join.

connection.urlRequiredstring1–2048 characters

The LiveKit server, wss://… (ws:// in development).

connection.tokenRequiredstring1–4096 characters

The participant token: join before expiresAt; it publishes a microphone and data only.

connection.roomRequiredstring1–200 characters

v1VoiceRoomName.

connection.identityRequiredstring1–200 characters

v1VoiceViewerIdentity.

connection.expiresAtRequiredstring (date-time)

An ISO 8601 instant.

dispatchstring1–32 characters

ready: whether the agent was dispatched now (dispatched) or already serves the room (joined); open.

Errors

  • 400invalid_input
  • 401invalid_token, session_expired
  • 403scope_required
  • 404not_found
  • 409stale_epoch
  • 429rate_limited
  • 503retry_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

NameInTypeDescription
idRequiredpathstring

The viewer session's id (session.id in the mint answer).

localequerystring

A UI or reply language: a BCP 47 tag (en, pt-BR, zh-Hant-TW).

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.

FieldTypeDescription
uploadRefstring1–200 characters
transcriptRequiredstring≤ 500 characters
durationMsRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

voiceRequiredobject

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 V1_VOICE_LIMITS pressMaxMs and what is left).

voice.secondsLeftRequiredinteger0–9007199254740991
voice.pressMaxMsRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

Errors

  • 401invalid_token, session_expired
  • 403scope_required, ai_unavailable
  • 404not_found
  • 413body_too_large
  • 415unsupported_media_type
  • 429rate_limited
  • 503retry_later