avatar_id values cannot be changed or replaced in v1. Added avatars do not become active automatically; after avatar.added, use session.update to select one. If any avatar in the event is invalid, none of the avatars in that event are registered.
avatar.add registers new avatar IDs. It cannot replace an existing avatar or append source images to one. Wait for avatar.added before using a new avatar.
Event fields
string
Client-generated id for this event.
string
required
Event type. Must be
avatar.add.array
required
Additional avatar definitions to register. Uses the same avatar object shape as
avatars[] in Create Session.string
required
Caller-defined avatar id, unique within the session.
string
The avatar’s identity, speaking style, and response rules.
object
Optional per-avatar TTS configuration for sessions that omit
pipeline_config.tts_config and require different voices for different avatars. Provide provider, provider_voice_id, and model. Otherwise omit this object; the added avatar uses the session TTS configuration.string
required
TTS
provider, such as qwen-audio-3.0-tts-flash_ws, elevenlabs, or qwen3tts. Required with provider_voice_id and model.string
required
Provider-side voice or style id. Required with
provider and model.string
required
Provider TTS model id. Required with
provider and provider_voice_id.number
Speech speed multiplier. Valid range is 0.7 to 1.2.
object
Visual rendering settings for avatar video. Required when this avatar can be selected in
video_avatar mode.string
Default visual instructions for this avatar, describing movement, posture, gaze, gestures, and on-camera presentation.
array
Registered source images available for this avatar. Required when image-based avatar video rendering is used.
string
required
Caller-defined source image id, unique within the avatar.
string
required
Image URL for this avatar video source image.
string
Optional description of the person, pose, and scene.
string
required
Image media type, such as
image/png or image/jpeg.string
With one usable source image, this field can be omitted. With multiple images and no explicit
source_image_id, use it to select the initial image.