> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vivix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# avatar.add

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.

**`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

<ParamField body="event_id" type="string">
  Client-generated id for this event.
</ParamField>

<ParamField body="type" type="string" required>
  Event type. Must be `avatar.add`.
</ParamField>

<ParamField body="avatars" type="array" required>
  Additional avatar definitions to register. Uses the same avatar object shape as `avatars[]` in Create Session.
</ParamField>

<ParamField body="avatars[].avatar_id" type="string" required>
  Caller-defined avatar id, unique within the session.
</ParamField>

<ParamField body="avatars[].instructions" type="string">
  The avatar’s identity, speaking style, and response rules.
</ParamField>

<ParamField body="avatars[].voice" type="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.
</ParamField>

<ParamField body="avatars[].voice.provider" type="string" required>
  TTS `provider`, such as `qwen-audio-3.0-tts-flash_ws`, `elevenlabs`, or `qwen3tts`. Required with `provider_voice_id` and `model`.
</ParamField>

<ParamField body="avatars[].voice.provider_voice_id" type="string" required>
  Provider-side voice or style id. Required with `provider` and `model`.
</ParamField>

<ParamField body="avatars[].voice.model" type="string" required>
  Provider TTS model id. Required with `provider` and provider\_voice\_id.
</ParamField>

<ParamField body="avatars[].voice.speed" type="number">
  Speech speed multiplier. Valid range is 0.7 to 1.2.
</ParamField>

<ParamField body="avatars[].visual" type="object">
  Visual rendering settings for avatar video. Required when this avatar can be selected in `video_avatar` mode.
</ParamField>

<ParamField body="avatars[].visual.instructions" type="string">
  Default visual instructions for this avatar, describing movement, posture, gaze, gestures, and on-camera presentation.
</ParamField>

<ParamField body="avatars[].visual.source_images" type="array">
  Registered source images available for this avatar. Required when image-based avatar video rendering is used.
</ParamField>

<ParamField body="avatars[].visual.source_images[].source_image_id" type="string" required>
  Caller-defined source image id, unique within the avatar.
</ParamField>

<ParamField body="avatars[].visual.source_images[].url" type="string" required>
  Image URL for this avatar video source image.
</ParamField>

<ParamField body="avatars[].visual.source_images[].description" type="string">
  Optional description of the person, pose, and scene.
</ParamField>

<ParamField body="avatars[].visual.source_images[].media_type" type="string" required>
  Image media type, such as `image/png` or `image/jpeg`.
</ParamField>

<ParamField body="avatars[].visual.default_source_image_id" type="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.
</ParamField>

<RequestExample>
  ```json avatar.add theme={null}
  {
    "event_id": "evt_avatar_add_001",
    "type": "avatar.add",
    "avatars": [
      {
        "avatar_id": "host_c",
        "instructions": "You are Host C, a practical product specialist.",
        "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"
        }
      }
    ]
  }
  ```
</RequestExample>