Customer Support Avatar

A copy-ready sample case: Claire, a customer support avatar built around conversation, expression, and emotion. The default demo accepts both microphone speech and typed messages, generates replies with an LLM, and renders audio and video in real time — a complete walk through the Streaming Avatar flow, from creating to closing the session.

Customer Support

Engage users in natural, personalized conversations using your knowledge base.

Before you start, follow the Quickstart in Introduction to create an account and generate an API key. All REST requests use https://api.vivix.ai as the base URL and carry the Authorization: Bearer <API_KEY> header. Every REST response is wrapped in {"code": 0, "message": "success", "data": {...}} — the business fields live in data. Claire is a customer support avatar who sits in an office, facing the camera: she answers product questions, troubleshoots integration issues, and keeps a calm, professional expression and tone throughout the conversation. This scenario covers the most typical Streaming Avatar usage — conversation-driven: you write what the user says into the conversation context, the avatar generates a reply from that context, and the reply streams out in real time as speech, rendered video, and word-by-word captions.

Core Concepts

A Streaming Avatar session is built from four objects:

Concept	Description
Session	A single realtime session. Created over REST; the response returns `session_id`, the WSS control channel (`control`), and media stream info (`delivery.media`).
Avatar	A switchable character definition inside the session. This sample provides `visual` (reference images) and `instructions` (persona and tone), and configures the session voice separately with `pipeline_config.tts_config`.
Conversation	The context of this session. You write what the user says — and extra facts from your business systems — as conversation items.
Response	One round of avatar output. `response.create` makes the current active avatar generate a reply from the context; fixed lines, singing, and dancing use `response.script`.

Three channels carry the flow, each with its own job:

REST (/v1/realtime-avatar/sessions) — the session lifecycle: create, retrieve, close.
WSS control channel (control.url, pointing at /v1/realtime-avatar/control) — sends and receives conversation / response / session events.
Media stream (chosen by delivery.media.transport; currently supports trtc and agora) — carries generated avatar audio and video downstream and user microphone audio upstream.

Step 1: Create a Session

Use POST /v1/realtime-avatar/sessions to initialize the session’s selectable avatars, default avatar, voice pipeline, and conversation defaults. avatars[] defines Claire’s appearance and persona: visual.source_images provides the reference images (they decide what the avatar looks like and what scene she is in), instructions writes the persona, and the top-level pipeline_config.tts_config selects the voice used for generated speech.

Request

curl -X POST https://api.vivix.ai/v1/realtime-avatar/sessions \
  -H "Authorization: Bearer $VIVIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vivix-a1-stream",
    "session": {
      "mode": "video_avatar",
      "active_avatar_id": "claire",
      "source_image_id": "default"
    },
    "output": {
      "aspect_ratio": "9:16",
      "resolution": "480p"
    },
    "pipeline_config": {
      "tts_config": {
        "tts_provider": "qwen-audio-3.0-tts-flash_ws",
        "tts_voice_id": "loongeva_v3.6",
        "tts_model_id": "qwen-audio-3.0-tts-flash"
      }
    },
    "conversation": {
      "instructions": "Help users understand Vivix products and API onboarding. Ask one clarifying question when the goal is unclear.",
      "response_defaults": {
        "temperature": 0.7,
        "max_output_tokens": 512
      },
      "turn_detection": {
        "type": "server_vad",
        "silence_duration_ms": 500
      },
      "input_audio_transcription": {
        "enabled": true,
        "language": "en"
      }
    },
    "avatars": [
      {
        "avatar_id": "claire",
        "instructions": "You are Claire Bennett, a calm, professional Vivix customer support specialist. Identify the user goal first, explain in plain language, and recommend the clearest next step. Output only natural spoken language - no speaker labels, no narration, no stage directions, no Markdown, no emojis.",
        "visual": {
          "default_source_image_id": "default",
          "source_images": [
            {
              "source_image_id": "default",
              "url": "https://cdn.example.com/avatars/claire.png",
              "description": "A customer support specialist facing the camera in a brightly lit studio, front view.",
              "media_type": "image/png"
            }
          ]
        }
      }
    ]
  }'

Model choice. The model field also accepts the lighter vivix-a1-stream-lite variant — see Models for the differences. For the full field tables, see the Sessions API.

The response (some fields omitted for readability):

Response

{
  "code": 0,
  "message": "success",
  "data": {
    "session_id": "avatar-session-123",
    "status": "active",
    "session": {
      "mode": "video_avatar",
      "active_avatar_id": "claire",
      "source_image_id": "default"
    },
    "control": {
      "url": "wss://api.vivix.ai/v1/realtime-avatar/control?session_id=avatar-session-123",
      "client_secret": "ctl_..."
    },
    "output": {
      "aspect_ratio": "9:16",
      "resolution": "480p",
      "fps": 24
    },
    "conversation": {
      "instructions": "Help users understand Vivix products and API onboarding. Ask one clarifying question when the goal is unclear.",
      "response_defaults": {
        "temperature": 0.7,
        "max_output_tokens": 512
      },
      "turn_detection": {
        "type": "server_vad",
        "silence_duration_ms": 500
      },
      "input_audio_transcription": {
        "enabled": true,
        "language": "en"
      }
    },
    "avatars": [
      {
        "avatar_id": "claire",
        "instructions": "You are Claire Bennett, ..."
      }
    ],
    "delivery": {
      "media": {
        "transport": "trtc",
        "trtc": {
          "sdk_app_id": "1400000000",
          "room_id": "avatar-session-123",
          "user_id": "viewer",
          "user_sig": "...",
          "publisher_user_id": "publisher_xxx"
        }
      }
    },
    "model": "vivix-a1-stream"
  }
}

From the response, save:

session_id
control.url and control.client_secret
delivery.media
the server-side effective session.mode / active_avatar_id / source_image_id

Step 2: Connect Media, Then the Control Channel

In video_avatar mode, join the TRTC media stream first. The default demo requests microphone permission after the user clicks Start and must run over HTTPS. Convert sdk_app_id to a number, pass the string room id as strRoomId, register remote video handlers before entering the room, and subscribe only to publisher_user_id:

TRTC setup

import TRTC from "trtc-sdk-v5";

const media = session.delivery.media.trtc;
const publisherUserId = media.publisher_user_id;
const { microphone } = await TRTC.getPermissions({
  request: true,
  types: ["microphone"],
});
const trtc = TRTC.create();

trtc.on(TRTC.EVENT.REMOTE_VIDEO_AVAILABLE, ({ userId, streamType }) => {
  if (userId !== publisherUserId) return;
  void trtc.startRemoteVideo({ userId, streamType, view: "avatar-video" });
});

await trtc.enterRoom({
  sdkAppId: Number(media.sdk_app_id),
  userId: media.user_id,
  userSig: media.user_sig,
  strRoomId: String(media.room_id),
});

if (microphone !== "denied") {
  await trtc.startLocalAudio({ publish: true });
}

If the user denies microphone permission, disable the microphone button and keep typed input available. After entering the media room, connect to the returned control.url and append the session token as a token query parameter:

Browser Control WSS

const controlUrl = new URL(session.control.url);
controlUrl.searchParams.set("token", session.control.client_secret);
const ws = new WebSocket(controlUrl.toString());

The query parameter name must be token and its value is the control.client_secret returned by Create Session. Do not open the original control.url without adding it, and do not name the query parameter client_secret. URL.searchParams preserves the existing session_id and encodes the credential. Server-side clients may instead send Authorization: Bearer <control.client_secret>. Wait for both TRTC enterRoom and the WebSocket open event before enabling voice and text input.

control.client_secret is the browser-safe, session-scoped control credential (never your API key). Do not log it or the complete control.url out of logs as well.

Step 3: Accept Voice and Text Input

The default demo keeps both a microphone button and a text box. Both input paths share the same conversation and response output events.

Voice Input

Step 1 enables turn_detection.type: "server_vad" and audio transcription. startLocalAudio publishes microphone audio to the same TRTC room. When the user finishes speaking, the server runs ASR, appends the user conversation item, and creates a response automatically. Voice turns do not send conversation.item.create or response.create from the client:

Voice turn

-> microphone audio over TRTC
<- input_audio.speech_started
<- conversation.item.input_audio_transcription.delta
<- input_audio.speech_stopped
<- conversation.item.input_audio_transcription.completed
<- conversation.item.created
<- response.created

Text Input

Use conversation.item.create to write a submitted text message into the conversation context:

conversation.item.create

{
  "event_id": "evt_item_create_001",
  "type": "conversation.item.create",
  "item": {
    "type": "message",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "How do I create an API key?"
      }
    ]
  }
}

The server confirms with conversation.item.created:

conversation.item.created

{
  "event_id": "evt_item_created_001",
  "type": "conversation.item.created",
  "previous_item_id": null,
  "item": {
    "id": "item_001",
    "type": "message",
    "status": "completed",
    "role": "user",
    "content": [
      {
        "type": "input_text",
        "text": "How do I create an API key?"
      }
    ]
  }
}

Wait for this acknowledgment before sending response.create. Do not write conversation.item.create and response.create back-to-back in the same send loop; the response could otherwise start before the context item is confirmed. Two things to note:

conversation.item.create for typed input only adds an item to the context — it does not automatically make the avatar speak. After the acknowledgment, send response.create. In server_vad mode, the server performs both steps for voice input.
When previous_item_id is omitted, the item is appended to the end of the context; pass it only when you need to insert after a specific item.

Step 4: Trigger a Reply for Text Input

After receiving conversation.item.created for typed input, send response.create. The current active avatar generates a reply from the conversation context:

response.create

{
  "event_id": "evt_response_create_001",
  "type": "response.create",
  "response": {
    "scheduling_policy": "interrupt"
  }
}

scheduling_policy defaults to interrupt (interrupt the current response and run the new one immediately) — see the queueing and interruption section of the Live Performance sample case. Server events then arrive in order on the control channel. For captions, use response.output_text.delta for word-by-word display and response.output_text.done for the final text:

response.output_text.delta

{
  "event_id": "evt_text_delta_001",
  "type": "response.output_text.delta",
  "response_id": "resp_001",
  "item_id": "item_assistant_001",
  "output_index": 0,
  "delta": "Sure, "
}

response.output_text.done

{
  "event_id": "evt_text_done_001",
  "type": "response.output_text.done",
  "response_id": "resp_001",
  "item_id": "item_assistant_001",
  "output_index": 0,
  "text": "Sure, open API Keys in the developer platform, create a key, and copy it to a secure location."
}

Rendering and completion hinge on these lifecycle events:

response.done

{
  "event_id": "evt_response_done_001",
  "type": "response.done",
  "response": {
    "id": "resp_001",
    "status": "completed"
  }
}

response.render.started / response.render.stopped: the avatar audio and video for this response start / stop rendering on RTC.
response.done: the Response resource and its logical output stream are finished — the Vocal and Visual attached to the Response are all complete. It fires no matter which terminal state the response ends in; read the final status from response.done.response.status.
In video_avatar mode, treat response.done as the signal that a round of avatar output has fully finished.

Step 5: Close the Session

The default demo must provide an explicit End session button. If a response is still active, wait for its final response.done event, then close WSS, stop and destroy TRTC, and ask your own backend to close the session so remote resources are released. The Close Session REST call carries your VIVIX_API_KEY and must run on your backend — never from the browser:

Close session

// Runs in the browser: tear down the local WebSocket and TRTC objects,
// then ask your own backend to close the session. The real Close Session
// call carries your VIVIX_API_KEY and must run on your backend - never
// ship the key to the browser.
async function closeAvatarSession({ session, trtc, ws }) {
  ws.close(1000, "client close");
  await trtc.stopLocalAudio().catch(() => {});
  await trtc.exitRoom().catch(() => {});
  trtc.destroy();

  // Your backend holds VIVIX_API_KEY and calls
  // POST https://api.vivix.ai/v1/realtime-avatar/sessions/{session_id}/close
  const response = await fetch("/your-backend/close-avatar-session", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ session_id: session.session_id }),
  });
  if (!response.ok) {
    throw new Error("Failed to close the session.");
  }
}

Expression and Emotion: Writing Instructions

Claire’s expression and emotion are not driven by a dedicated interface — they come from how you write avatars[].instructions. Write instructions as “how the character speaks”, not “how the system works”:

avatars[].instructions defines only the persona and tone — it grants no tools or business data access. Put the task goal of the current application in conversation.instructions, and one-off directives for a single generation in response.instructions (priority: avatar < conversation < response; see Write spoken instructions).
For production integrations, explicitly constrain the output to plain spoken language: only what the character would actually say out loud — no character names, no narration, no action descriptions, no stage directions, no Markdown, no JSON, no parenthetical asides, no emojis.
When the user asks the avatar to perform an action, do not let the model describe the action in text — actions are driven by response.script.visual.prompt or session state (see the Live Performance sample case).

Emotion is expressed through approved audio tags: let the model insert square-bracket tags into its lines. A tag describes vocal delivery — the emotion of the voice and non-verbal sounds — not actions. Approved tags fall into two groups:

Category	Approved tags
direction (emotional direction)	`[happy]` `[sad]` `[excited]` `[angry]` `[annoyed]` `[appalled]` `[thoughtful]` `[surprised]` `[sarcastic]` `[curious]` `[mischievously]` `[frustrated]` `[dismissive]` `[sympathetic]` `[reassuring]` `[warmly]` `[nervously]` `[sheepishly]` `[desperately]` `[deadpan]` `[cautiously]` `[dramatically]` `[impressed]` `[delighted]` `[amazed]`
non-verbal (non-verbal sounds)	`[laughs]` `[laughing]` `[chuckles]` `[giggles]` `[sighs]` `[exhales]` `[exhales sharply]` `[inhales deeply]` `[whispers]` `[clears throat]` `[crying]` `[snorts]` `[short pause]` `[long pause]`

The recommended constraint block (append it to the end of your instructions):

Constraint template

Output only Claire's spoken words and approved square-bracket audio tags.
No speaker labels, no narration, no stage directions, no motion descriptions, no emojis, no parentheses.
Every response must include 1 or 2 approved non-verbal tags.
Use at most 1 approved direction tag, only when the emotion is clear.
Place tags immediately before the sentence or clause they modify, or at a natural pause point.
Do not cluster tags together. Tags describe vocal delivery only, not actions.
Never invent tags. If unsure, use a safe non-verbal tag such as [short pause] or [exhales].

Under these constraints, one of Claire’s replies looks like this:

Sample reply

[warmly] Let me make sure I understand. [short pause] What are you hoping to build with Vivix?

Minimal Runnable Event Sequence

Putting the steps together, the default demo connects in this order:

Connection

HTTP POST /v1/realtime-avatar/sessions
-> request microphone permission
-> TRTC enterRoom
-> TRTC startLocalAudio if permission is granted
-> append token=<control.client_secret> to control.url and connect WSS

For a typed turn:

Text input

-> conversation.item.create(user message)
<- conversation.item.created
-> response.create

For a voice turn:

Voice input

-> microphone audio over TRTC
<- input_audio.speech_started
<- conversation.item.input_audio_transcription.delta
<- input_audio.speech_stopped
<- conversation.item.input_audio_transcription.completed
<- conversation.item.created

Both input paths then use the same response output stream:

Response output

<- response.created
<- response.render.started
<- response.output_text.delta
<- response.output_text.done
<- response.output_item.done
<- response.render.stopped
<- response.done

When the demo ends:

Cleanup

-> WebSocket close
-> TRTC stopLocalAudio / exitRoom / destroy
HTTP POST /v1/realtime-avatar/sessions/{session_id}/close

Full field definitions for every event are in Client events and Server events.

Next Steps

Live Performance — the other sample case, built around actions: use response.script to directly drive singing, dancing, and fixed lines.
Script speech and performances — directed movement and scripted audio.
Change outfits and scenes — switch the avatar image during a session.
Add tools to the character — function calls.
API References · Sessions — REST endpoints and parameter details.
API References · Client events / Server events — the complete event mechanism.
Streaming World — realtime interactive video worlds driven by the W-series models; coming soon.

Overview

A1: Streaming Avatar

W1: Streaming World

Blazing Fast Video Generation