Skip to main content
Asks the service to create a response. A regular response uses model inference. When you supply response.script, the service renders the supplied vocal and visual content, with an optional rewrite of the visual prompt. The session state determines which avatar responds. after_current_response allows only one pending response. Keep longer queues in your application and submit them in sequence. response.input replaces the default context for this response. [] supplies no context. Complete inline items can be sent directly; an item_reference must already exist.

Event fields

string
Client-generated id for this event.
string
required
Event type. Must be response.create.
object
Per-response creation parameters. Fields set here apply only to this response.
string
Controls where the response is added. Use auto to write to the default conversation, or none for an out-of-band response that does not write output to the default conversation.
string
Controls what happens when the session is already busy. Use interrupt to cancel the active response or render and start this response, reject_if_busy to reject this event with an error, or after_current_response to run this response immediately after the current response finishes. Defaults to interrupt. Interrupted responses still emit their existing terminal lifecycle events, such as response.render.stopped followed by response.done.
array
Input items to include in the model context when asking the model to respond. Each array item is either an item_reference or a raw conversation_item. Providing this field creates a response-specific context instead of using the default conversation; an empty array clears context for this response. Invalid when script is supplied.

Variant: item_reference

References an existing item already present in the session.
string
required
Use item_reference.
string
required
Existing item id to include in the response context.

Variant: conversation_item

A raw conversation item, using the same message, function call, and function call output shapes documented for conversation.item.create.
integer | string
Maximum output tokens for this response, inclusive of tool calls. Use an integer or inf. Invalid when script is supplied.
array
Tools available for this response. When supplied, this overrides session conversation tools for this response only. Invalid when script is supplied.
Function tool in response.tools[] Function tool with type, name, optional description, and optional JSON Schema parameters.
object
Direct avatar output to render exactly as provided. When supplied, no LLM reply generation or tool calling occurs, and input, tools, and max_output_tokens are invalid.
object
Exact vocal output for the active avatar. Provide vocal, visual, or both.

Variant: speech

Synthesized speech from exact text.
string
required
Use speech.
string
required
Exact spoken text. This text also streams through response.output_text.delta and response.output_text.done.

Variant: speech_asset

Synthesized speech from a reusable speech text asset.
string
required
Use speech_asset.
string
required
Previously registered asset from assets.speech_text. The asset text is exact spoken text and streams through response.output_text.delta and response.output_text.done.

Variant: audio

Supplied audio used to drive the avatar.
string
required
Use audio.
string
required
Required MIME type for the supplied audio. Supported values are audio/wav and audio/mpeg. The bytes served by url or encoded in audio must match this value.When script.accompaniment_audio is supplied, use a URL containing isolated voice with the accompaniment removed. Both stems accept WAV (audio/wav) or MP3 (audio/mpeg), including floating-point WAVs. Without that optional field, existing WAV, MP3, and Base64 audio behavior is unchanged.
string
HTTPS URL for an audio file to render through the avatar. The URL must be directly fetchable by Vivix without custom request headers. Provide exactly one of url or audio.
string
Base64-encoded audio file bytes to render through the avatar. Do not include a data URL prefix. Provide exactly one of url or audio.

Variant: audio_asset

Reusable audio asset used to drive the avatar.
string
required
Use audio_asset.
string
required
Previously registered asset from assets.audio.
object
Optional accompaniment or background-sound stem, mixed with vocal for playback. Only the separate vocal stem enters the audio encoder and DiT to drive mouth movement; the accompaniment never conditions the avatar. Omit this object to keep existing single-audio script behavior.Try this when background music makes the voice hard to distinguish in your original audio and the avatar’s mouth shapes or timing are inaccurate. Providing an isolated vocal gives the model a clearer signal and can improve lip sync while the aligned accompaniment continues to play in sync.Requires vocal.type: "audio" with vocal.url. Both files accept directly fetchable HTTPS WAV or MP3, matching ordinary vocal audio; WAV files may use integer or floating-point samples. Each file must be at most 300 seconds and 32 MiB. Supply isolated voice in vocal.url and the aligned music/background stem here. Vivix does not separate vocals from a mixed recording.Vivix automatically decodes both stems and normalizes them to mono PCM16 at 16 kHz; you do not need to preconvert their sample format, sample rate or channels. Both must preserve the same original time zero, including leading silence, and have equal sample counts after normalization. No timestamp or offset field is needed: sample zero in one file aligns with sample zero in the other. Vivix does not trim silence, loop, time-stretch, or infer an offset.Providing this object enables paired playback; no separate feature switch is required. It cannot be combined with text speech, inline Base64 audio, or audio assets. A failed download, decode, or length check fails the paired response rather than playing only the vocal.
string
required
Directly fetchable HTTPS URL of the accompaniment WAV or MP3. Required when accompaniment_audio is supplied.
string
required
Use audio/wav for WAV or audio/mpeg for MP3. Required when accompaniment_audio is supplied.
number
Accompaniment playback gain in decibels. Optional; defaults to 0, with a finite range of -60 to 6. It does not change vocal conditioning. A constant shared gain may reduce both stems in the playback mix to avoid clipping.
object
Motion instructions for the active avatar.
string
Inline instruction for avatar movement, posture, gaze, gestures, or presentation. Separate multiple ordered action descriptions with [SHOT_SEP].
string
Previously registered asset from assets.visual_prompts. Provide exactly one of prompt or visual_prompt_asset_id.
integer
Target duration of each visual action segment in milliseconds. Defaults to 5000 when omitted. When prompt contains [SHOT_SEP], this value applies to each segment, not the combined sequence. For example, three segments at 5000 milliseconds each plan about 15 seconds of motion. It does not change the duration of supplied audio or guarantee exact browser playback timing.
boolean
default:"false"
When true, Vivix can expand a short action cue into a movement prompt that fits the current scene. Works with inline prompts and visual prompt assets. If enhancement is unavailable, Vivix continues with the supplied prompt. See Scripted performances for an example.
Script behavior. Response scheduling. The session is busy until the active response reaches terminal response.done. If rendering starts, response.render.stopped is emitted first and response.done follows. A queued response uses the inputs, images, character behavior, and assets selected when it was submitted. Later updates do not change it. response.created is emitted when the queued response starts.