Skip to content
Jami3D
Developer docs menu

REST API: Conversation

Every operation of this group with its parameters, body, answer and errors, as the OpenAPI document states them.

Live AI: a question or an AI Line answered as an event stream, its cancel, the shared transcript, and the session-bound media links the events hand out.

Run a turn (event stream)

POST/v1/sessions/{id}/turnsViewer token

A fetch POST answered with Server-Sent-Events framing: each event is an event: <type> line and a data: <json> line, and a comment line (: hb) comes every 15 s. Errors before the stream opens are /v1 errors; a refusal is the turn.refused event, not an error. Closing the request cancels the turn.

Parameters

NameInTypeDescription
idRequiredpathstring

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

Request body (application/json)

FieldTypeDescription
When kind is “viewer”

A typed (or locally transcribed) question to ONE addressee at an open Beat.

clientTurnIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

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.

viewobject

What the viewer sees, by alias only — the focused object, the ones in view — validated by the server against what is perceivable at the turn's position. Never free text.

view.focusstring

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

view.lookingAtstring[]≤ 16 items
localestring≤ 35 characters

The reply language; absent: the session's.

outputobject

Absent: { audio: true }.

output.audioRequiredboolean
addresseeRequiredstring

The speaker asked: the narrator's or a speaking character's or prop's alias.

textRequiredstring1–500 characters
source"viewer_text" | "viewer_voice"

Absent: viewer_text.

beatIdRequiredstring1–160 characters

The Beat it is asked at (an interactive scene's synthetic Beat is scene:{sceneId}).

When kind is “viewer_audio”

A recorded push-to-talk clip for networks that block WebRTC: uploaded first (≤ 8 MB), named here by its upload reference, transcribed by the server, then answered like a typed question.

clientTurnIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

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.

viewobject

What the viewer sees, by alias only — the focused object, the ones in view — validated by the server against what is perceivable at the turn's position. Never free text.

view.focusstring

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

view.lookingAtstring[]≤ 16 items
localestring≤ 35 characters

The reply language; absent: the session's.

outputobject

Absent: { audio: true }.

output.audioRequiredboolean
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.

uploadRefRequiredstring1–200 characters
When kind is “ai_line”

An AI Line the story reached (a clip's start, or a rule's startAiLine): the client names the line by its id and nothing else — its directive and fallback are the server's.

clientTurnIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

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.

viewobject

What the viewer sees, by alias only — the focused object, the ones in view — validated by the server against what is perceivable at the turn's position. Never free text.

view.focusstring

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

view.lookingAtstring[]≤ 16 items
localestring≤ 35 characters

The reply language; absent: the session's.

outputobject

Absent: { audio: true }.

output.audioRequiredboolean
lineIdRequiredstring1–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.

When kind is “arrival”

The narrator's answer on arrival: once the client's navigation.arrived of an AI navigation was accepted, it asks for the narrator to answer the request that took the viewer there — once per navigation; position is where the viewer arrived. Refused (beat_closed) when no such request is waiting: none was made, it was answered already, or an Undo took the viewer back.

clientTurnIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

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.

viewobject

What the viewer sees, by alias only — the focused object, the ones in view — validated by the server against what is perceivable at the turn's position. Never free text.

view.focusstring

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

view.lookingAtstring[]≤ 16 items
localestring≤ 35 characters

The reply language; absent: the session's.

outputobject

Absent: { audio: true }.

output.audioRequiredboolean

Response 200

A stream of events: an event: <type> line and a data: <json> line per event, a blank line after each, and a comment line every 15 s.

text/event-stream: each event's data

FieldTypeDescription
When type is “turn.accepted”

The turn is the server's now: its id, and who speaks.

turnIdRequiredstring (uuid)
clientTurnIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

kindRequired"viewer" | "viewer_audio" | "ai_line" | "arrival"
speakerRequiredstring1–200 characters

The speaker key of who answers.

lineIdstring1–160 characters

ai_line: the line.

When type is “speaker.state”
turnIdRequiredstring (uuid)
speakerRequiredstring1–200 characters
stateRequired"thinking" | "speaking" | "idle"
When type is “effect”
turnIdRequiredstring (uuid)
speechIdRequiredstring1–160 characters
effectRequiredone of
When kind is “gesture”
effect.entityIdRequiredstring1–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.

effect.motionIdRequiredstring1–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.

effect.intensityRequirednumber0–1
effect.pinRootRequiredboolean

Live gestures never move a character: root motion discarded.

effect.expressionobject
effect.expression.expressionRequiredstring1–64 characters
effect.expression.intensityRequirednumber0–1
When kind is “expression”
effect.entityIdRequiredstring1–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.

effect.expressionRequiredstring1–64 characters
effect.intensityRequirednumber0–1
When kind is “look_at”
effect.entityIdRequiredstring1–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.

effect.targetRequiredone of
When kind is “viewer”
When kind is “entity”
effect.target.entityIdRequiredstring1–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.

When kind is “navigate”
effect.toBeatIdRequiredstring1–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.

effect.landingRequired"chapterStart" | "hold"
When kind is “show_place”
effect.entityIdRequiredstring1–160 characters

The AI-showable viewpoint of the current scene.

When kind is “object”
effect.entityIdRequiredstring1–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.

effect.behaviorIdstring1–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.

effect.actionRequiredstring1–64 characters
effect.changeRequiredobject

What changed about an object: a toggle's state, a book's spread, a visibility override.

effect.change.statestring1–64 characters
effect.change.spreadinteger0–9007199254740991
effect.change.visibleboolean
When type is “text.delta”

Streamed reply text (the transcript's interim line).

turnIdRequiredstring (uuid)
speechIdRequiredstring1–160 characters
textRequiredstring≤ 4000 characters
When type is “audio.format”

How the audio.chunks of a speech are encoded: little-endian 16-bit PCM.

turnIdRequiredstring (uuid)
speechIdRequiredstring1–160 characters
encodingRequired"pcm_s16le"
sampleRateRequiredinteger0–9007199254740991
channelsRequiredinteger1–2
When type is “audio.chunk”

About 100 ms of streamed speech, base64, numbered from 0 per speech.

turnIdRequiredstring (uuid)
speechIdRequiredstring1–160 characters
seqRequiredinteger0–9007199254740991
dataRequiredstring≤ 1048576 characters
When type is “audio.url”

A whole prepared speech (an AI Line made ahead) instead of streamed chunks.

turnIdRequiredstring (uuid)
speechIdRequiredstring1–160 characters
audioRequiredobject

A whole speech file: its renditions and how long it plays.

audio.renditionsRequiredobject[]1–4 items
audio.renditions[].codecRequired"opus" | "aac"
audio.renditions[].urlRequiredstring1–2048 characters
audio.renditions[].offsetMsRequirednumber≥ 0
audio.renditions[].primingMsnumber≥ 0
audio.durationMsRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

alignmentobject

Where a speech file's alignment sidecar is: the same kind of link as its audio.

alignment.urlRequiredstring1–2048 characters
When type is “alignment”
turnIdRequiredstring (uuid)
speechIdRequiredstring1–160 characters
alignmentRequiredobject

Word and viseme timings of streamed speech, in ms from the start of its audio (the alignment sidecar's shape). visemeSource: phonemes, graphemes or acoustic (an open vocabulary).

A streamed speech may send several alignment events while it is synthesised: each carries the timings of the speech FROM ITS START through what has been synthesised so far, so the latest one replaces those before it; the last, sent just before speech.end, covers the whole speech and adds its captions. Each carries the synthetic mark of the voice that speaks it (generator, added within v1: absent from a server before it).

alignment.wordsRequiredobject[]
alignment.words[].textRequiredstring
alignment.words[].startMsRequirednumber≥ 0
alignment.words[].endMsRequirednumber≥ 0
alignment.visemesRequiredobject[]
alignment.visemes[].visemeRequiredstring1–8 characters
alignment.visemes[].startMsRequirednumber≥ 0
alignment.visemes[].endMsRequirednumber≥ 0
alignment.visemes[].weightnumber
alignment.visemeSourceRequiredstring1–32 characters
alignment.captionsobject[]
alignment.captions[].textRequiredstring
alignment.captions[].startMsRequirednumber≥ 0
alignment.captions[].endMsRequirednumber≥ 0
alignment.generatorobject

The machine-readable mark of synthetic speech: the speech is AI-generated (synthetic: true), made by by (jami3d) with a provider's TTS model. Pre-generated speech carries it in its sidecar and its container; live speech carries it on its alignment (added within v1, P8).

alignment.generator.syntheticRequiredtrue
alignment.generator.byRequiredstring1–64 characters
alignment.generator.providerRequiredstring1–64 characters
alignment.generator.modelRequiredstring1–128 characters
When type is “speech.end”
turnIdRequiredstring (uuid)
speechIdRequiredstring1–160 characters
When type is “line.fallback”

An AI Line answered with its pre-generated fallback: the variant the server selected for the session (one per combination of its tokens' values — "Cat, you chose B; the right answer was C"), spoken and captioned like a scripted line. Nothing about it is billed.

turnIdRequiredstring (uuid)
lineIdRequiredstring1–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.

speechIdRequiredstring1–160 characters

Groups the effects, audio and alignment of one utterance.

speakerRequiredstring1–200 characters

The speaker key: narrator, cast:{castId} or prop:{entityId}.

textRequiredstring≤ 4000 characters
audioobject

A whole speech file: its renditions and how long it plays.

audio.renditionsRequiredobject[]1–4 items
audio.renditions[].codecRequired"opus" | "aac"
audio.renditions[].urlRequiredstring1–2048 characters
audio.renditions[].offsetMsRequirednumber≥ 0
audio.renditions[].primingMsnumber≥ 0
audio.durationMsRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

alignmentobject

Where a speech file's alignment sidecar is: the same kind of link as its audio.

alignment.urlRequiredstring1–2048 characters
When type is “turn.refused”

The turn was refused — not an error: the stream ends here, playback goes on. reason is one of TURN_REFUSED_REASONS (@jami3d/protocol/errors, an open vocabulary a reader must not fail on); canned, the speaker's pre-generated line for it; ai, the session's AI status that decided it.

turnIdRequiredstring (uuid)
clientTurnIdRequiredstring (uuid)

A server-minted id (sessions, projects, releases, users): a UUID.

reasonRequiredstring1–64 characters
cannedobject
canned.speechIdRequiredstring1–160 characters

Groups the effects, audio and alignment of one utterance.

canned.speakerRequiredstring1–200 characters

The speaker key: narrator, cast:{castId} or prop:{entityId}.

canned.textRequiredstring≤ 4000 characters
canned.audioobject

A whole speech file: its renditions and how long it plays.

canned.audio.renditionsRequiredobject[]1–4 items
canned.audio.renditions[].codecRequired"opus" | "aac"
canned.audio.renditions[].urlRequiredstring1–2048 characters
canned.audio.renditions[].offsetMsRequirednumber≥ 0
canned.audio.renditions[].primingMsnumber≥ 0
canned.audio.durationMsRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

canned.alignmentobject

Where a speech file's alignment sidecar is: the same kind of link as its audio.

canned.alignment.urlRequiredstring1–2048 characters
aiobject

The session's live-AI status: the level and every reason that holds at it, and the scopes the token carries. The UI hides voice at text and shows "Live answers are paused" at off.

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).

When type is “turn.final”

The turn is complete: everything it said has been sent, and what it cost is recorded. usage: Studio draft sessions only.

turnIdRequiredstring (uuid)
usageobject

What a turn's provider calls came to — on Studio draft sessions only, for the AI panel's Test chat: the tokens of every round (cached ones included in promptTokens), how many rounds ran, the time to the first words, the tool calls with what became of each (applied, coerced, refused; open), and the credits the turn was priced at.

usage.promptTokensRequiredinteger0–9007199254740991
usage.cachedTokensRequiredinteger0–9007199254740991
usage.completionTokensRequiredinteger0–9007199254740991
usage.roundsRequiredinteger0–9007199254740991
usage.firstTextMsinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

usage.toolsobject[]≤ 16 items
usage.tools[].nameRequiredstring1–64 characters
usage.tools[].outcomeRequiredstring1–32 characters
usage.creditsMilliinteger0–9007199254740991
When type is “error”

The turn failed after the stream began; code is a /v1 error code.

turnIdstring (uuid)

The server's id of the turn: on every event (DELETE …/turns/{turnId} cancels it).

codeRequiredstring1–64 characters
messageRequiredstring≤ 2000 characters
When type is “facts”

The server facts the turn journaled — conversation.turn (a question accepted at a Beat), object.changed with an ai cause, navigation.requested — sent BEFORE the effects that show them, so the player folds them like an events answer's facts instead of re-reading its state. Read tolerantly: a fact of a kind the reader does not know is skipped.

turnIdRequiredstring (uuid)
factsRequiredany[]

A journal as a reader takes it: every fact it knows, in order; a fact of a kind it does not know (a newer server's) is skipped rather than failing the whole answer.

Errors

  • 400invalid_input
  • 401invalid_token, session_expired
  • 403scope_required
  • 404not_found
  • 409stale_epoch, rewind_required
  • 429rate_limited

Open a session's private media

GET/v1/media/{token}/{path}No bearer token

The token is part of the path: the link itself is the credential.

Parameters

NameInTypeDescription
tokenRequiredpathstring

The link's signature, as a turn event handed it out.

pathRequiredpathstring

The file, after the token (it may contain slashes).

Response 302

A redirect to a short-lived download of the file. An unknown, tampered, expired or foreign link and an ended session are all the same 404.

Errors

  • 404not_found

Cancel a turn

DELETE/v1/sessions/{id}/turns/{turnId}Viewer token

Parameters

NameInTypeDescription
idRequiredpathstring

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

turnIdRequiredpathstring

The turn's id (turnId of its events).

Response 204

No content: whether the turn still ran, had ended or never existed.

Errors

  • 401invalid_token, session_expired

Read the shared transcript

GET/v1/sessions/{id}/conversationViewer token

Parameters

NameInTypeDescription
idRequiredpathstring

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

afterSeqqueryinteger

The entries after this one (exclusive): the last seq of the previous page.

limitqueryinteger

Response 200

The transcript since the conversation's window start, a page at a time.

FieldTypeDescription
epochRequiredinteger0–9007199254740991

The session's epoch: a rewind since erased what came after where it went back to.

entriesRequiredobject[]
entries[].seqRequiredinteger1–9007199254740991

The log's order; the next page starts after the last one.

entries[].kindRequiredstring1–32 characters

utterance, event or directive_result (an open vocabulary).

entries[].sourceRequiredstring1–32 characters

Where it came from: viewer_text, viewer_voice, scripted, ai_line, live_reply, player, server (an open vocabulary).

entries[].anchorRequiredobject

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.

entries[].anchor.visitRequiredinteger1–9007199254740991
entries[].anchor.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.

entries[].anchor.msRequiredinteger0–9007199254740991

A non-negative integer count or time in milliseconds.

entries[].beatIdstring1–160 characters

The Beat it happened at (an interactive scene's synthetic Beat is scene:{sceneId}).

entries[].speakerstring1–200 characters

Who said it: viewer, narrator, cast:{castId} or prop:{entityId}.

entries[].addresseestring1–200 characters

Who it was said to: a speaker key, or all.

entries[].textstring≤ 4000 characters
entries[].langstring≤ 35 characters

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

entries[].turnIdstring (uuid)

The server's turn that wrote it.

entries[].clientTurnIdstring (uuid)

The client's id of the turn: on the viewer's question, and on an AI Line's words.

entries[].eventstring1–32 characters

An event's kind: quiz_result, object_state, navigation, marker (an open vocabulary).

entries[].quizobject

A quiz_result event.

entries[].quiz.quizIdRequiredstring1–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.

entries[].quiz.questionIdRequiredstring1–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.

entries[].quiz.respondentRequiredone of

Who answers a quiz: the viewer, or the viewer playing a cast member ("as Cat").

When kind is “viewer”
When kind is “character”
entries[].quiz.respondent.castIdRequiredstring1–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.

entries[].quiz.answerTextRequiredstring≤ 4000 characters

The answer in words.

entries[].quiz.correctRequiredboolean
entries[].markerstring1–32 characters

A marker event: scene_entered, beat_reached, beat_skipped, skipped_range, … (open).

entries[].navigationobject

A navigation event: requested, confirmed, declined, arrived, visit_started (open).

entries[].navigation.eventRequiredstring1–32 characters
entries[].navigation.toBeatIdstring1–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.

entries[].objectobject

An object_state event: the object, what changed, and who changed it (viewer, story, ai).

entries[].object.entityIdRequiredstring1–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.

entries[].object.changeRequiredobject

What changed about an object: a toggle's state, a book's spread, a visibility override.

entries[].object.change.statestring1–64 characters
entries[].object.change.spreadinteger0–9007199254740991
entries[].object.change.visibleboolean
entries[].object.byRequiredstring1–16 characters
entries[].lineobject

A directive_result: the AI Line, and whether its pre-generated fallback spoke.

entries[].line.lineIdRequiredstring1–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.

entries[].line.fallbackRequiredboolean
moreRequiredboolean

More entries follow: ask again with afterSeq = the last entry's seq.

Errors

  • 400invalid_input
  • 401invalid_token, session_expired
  • 404not_found

Prepare an AI Line ahead

POST/v1/sessions/{id}/ai-lines/{lineId}/prepareViewer token

Fire and forget, about 12 s before the line: at most twice per line per epoch, never while live AI is off.

Parameters

NameInTypeDescription
idRequiredpathstring

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

lineIdRequiredpathstring

The AI Line's id.

Request body (application/json)

FieldTypeDescription
epochRequiredinteger0–9007199254740991
positionRequiredobject

Where the story is now.

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

The reply language the line will be taken in; absent: the session's.

outputobject

Absent: { audio: true } — its speech is made ahead too.

output.audioRequiredboolean

Response 202

Prepare an AI Line ahead

FieldTypeDescription
stateRequiredstring1–32 characters

Errors

  • 400invalid_input
  • 401invalid_token, session_expired
  • 404not_found
  • 409stale_epoch