avatar.add

{
  "event_id": "evt_avatar_add_001",
  "type": "avatar.add",
  "avatars": [
    {
      "avatar_id": "host_c",
      "persona": "You are Host C, a practical product specialist. Give clear, concise answers and use small gestures while explaining. Listen with relaxed eye contact.",
      "visual": {
        "source_images": [
          {
            "source_image_id": "front",
            "url": "https://api.vivix.ai/host-c-front.png",
            "description": "A man facing the camera in a brightly lit studio, front view.",
            "media_type": "image/png"
          }
        ],
        "default_source_image_id": "front"
      }
    }
  ]
}

{
  "event_id": "evt_avatar_add_001",
  "type": "avatar.add",
  "avatars": [
    {
      "avatar_id": "host_c",
      "persona": "You are Host C, a practical product specialist. Give clear, concise answers and use small gestures while explaining. Listen with relaxed eye contact.",
      "visual": {
        "source_images": [
          {
            "source_image_id": "front",
            "url": "https://api.vivix.ai/host-c-front.png",
            "description": "A man facing the camera in a brightly lit studio, front view.",
            "media_type": "image/png"
          }
        ],
        "default_source_image_id": "front"
      }
    }
  ]
}

Registers additional avatars while the session is live. Avatars are additive: existing 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.

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

required

Describe the avatar’s identity, speaking style, response habits, movement preferences, and listening behavior. Vivix prepares the character’s behavior from this Persona automatically. See Write a Persona.

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.

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. Its aspect ratio should match the session’s output.aspect_ratio (9:16 or 16:9)—a mismatched image will noticeably degrade video quality.

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.

{
  "event_id": "evt_avatar_add_001",
  "type": "avatar.add",
  "avatars": [
    {
      "avatar_id": "host_c",
      "persona": "You are Host C, a practical product specialist. Give clear, concise answers and use small gestures while explaining. Listen with relaxed eye contact.",
      "visual": {
        "source_images": [
          {
            "source_image_id": "front",
            "url": "https://api.vivix.ai/host-c-front.png",
            "description": "A man facing the camera in a brightly lit studio, front view.",
            "media_type": "image/png"
          }
        ],
        "default_source_image_id": "front"
      }
    }
  ]
}

Overview

A1: Streaming Avatar

W1: Streaming World

Blazing Fast Video Generation

Event fields