Create Session
curl --request POST \
--url https://api.vivix.ai/v1/realtime-avatar/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "vivix-a1-stream",
"idempotency_key": "avatar-create-123",
"region": "us-west",
"session": {
"mode": "video_avatar",
"active_avatar_id": "host_a",
"source_image_id": "front"
},
"output": {
"aspect_ratio": "9:16",
"resolution": "480p"
},
"pipeline_config": {
"tts_config": {
"tts_provider": "qwen-audio-3.0-tts-flash_ws",
"tts_voice_id": "longanhuan_v3.6",
"tts_model_id": "qwen-audio-3.0-tts-flash"
}
},
"assets": {
"audio": [
{
"asset_id": "welcome_jingle",
"url": "https://cdn.example.com/audio/welcome-jingle.wav",
"mime_type": "audio/wav"
}
],
"speech_text": [
{
"asset_id": "welcome_line",
"text": "Welcome back. I saved your place."
}
],
"visual_prompts": [
{
"asset_id": "wave_small",
"prompt": "smile and give a small wave"
}
]
},
"conversation": {
"instructions": "Answer as a concise livestream host.",
"tools": [
{
"type": "function",
"name": "lookup_product",
"description": "Look up product details by product id.",
"parameters": {
"type": "object",
"properties": {
"product_id": {
"type": "string"
}
},
"required": [
"product_id"
]
}
}
],
"response_defaults": {
"temperature": 0.7,
"max_output_tokens": 512
},
"turn_detection": {
"type": "server_vad",
"silence_duration_ms": 500
},
"input_audio_transcription": {
"enabled": true,
"language": "auto"
}
},
"avatars": [
{
"avatar_id": "host_a",
"instructions": "You are Host A, a warm livestream host who gives concise product-focused replies.",
"visual": {
"source_images": [
{
"source_image_id": "front",
"url": "https://cdn.example.com/avatars/host-a-front.png",
"description": "A woman facing the camera in a brightly lit studio, front view.",
"media_type": "image/png"
},
{
"source_image_id": "side",
"url": "https://cdn.example.com/avatars/host-a-side.png",
"description": "The same woman in the same studio, side view.",
"media_type": "image/png"
}
],
"default_source_image_id": "front"
}
},
{
"avatar_id": "host_b",
"instructions": "You are Host B, a calm expert who gives brief technical explanations.",
"visual": {
"source_images": [
{
"source_image_id": "front",
"url": "https://cdn.example.com/avatars/host-b-front.png",
"description": "A man facing the camera in a brightly lit studio, front view.",
"media_type": "image/png"
}
],
"default_source_image_id": "front"
}
}
],
"auto_close": {
"disconnected_timeout_seconds": 60,
"interaction_idle_timeout_seconds": 300
},
"delivery": {
"media": {
"transport": "trtc"
}
},
"max_duration_seconds": 300
}
'import requests
url = "https://api.vivix.ai/v1/realtime-avatar/sessions"
payload = {
"model": "vivix-a1-stream",
"idempotency_key": "avatar-create-123",
"region": "us-west",
"session": {
"mode": "video_avatar",
"active_avatar_id": "host_a",
"source_image_id": "front"
},
"output": {
"aspect_ratio": "9:16",
"resolution": "480p"
},
"pipeline_config": { "tts_config": {
"tts_provider": "qwen-audio-3.0-tts-flash_ws",
"tts_voice_id": "longanhuan_v3.6",
"tts_model_id": "qwen-audio-3.0-tts-flash"
} },
"assets": {
"audio": [
{
"asset_id": "welcome_jingle",
"url": "https://cdn.example.com/audio/welcome-jingle.wav",
"mime_type": "audio/wav"
}
],
"speech_text": [
{
"asset_id": "welcome_line",
"text": "Welcome back. I saved your place."
}
],
"visual_prompts": [
{
"asset_id": "wave_small",
"prompt": "smile and give a small wave"
}
]
},
"conversation": {
"instructions": "Answer as a concise livestream host.",
"tools": [
{
"type": "function",
"name": "lookup_product",
"description": "Look up product details by product id.",
"parameters": {
"type": "object",
"properties": { "product_id": { "type": "string" } },
"required": ["product_id"]
}
}
],
"response_defaults": {
"temperature": 0.7,
"max_output_tokens": 512
},
"turn_detection": {
"type": "server_vad",
"silence_duration_ms": 500
},
"input_audio_transcription": {
"enabled": True,
"language": "auto"
}
},
"avatars": [
{
"avatar_id": "host_a",
"instructions": "You are Host A, a warm livestream host who gives concise product-focused replies.",
"visual": {
"source_images": [
{
"source_image_id": "front",
"url": "https://cdn.example.com/avatars/host-a-front.png",
"description": "A woman facing the camera in a brightly lit studio, front view.",
"media_type": "image/png"
},
{
"source_image_id": "side",
"url": "https://cdn.example.com/avatars/host-a-side.png",
"description": "The same woman in the same studio, side view.",
"media_type": "image/png"
}
],
"default_source_image_id": "front"
}
},
{
"avatar_id": "host_b",
"instructions": "You are Host B, a calm expert who gives brief technical explanations.",
"visual": {
"source_images": [
{
"source_image_id": "front",
"url": "https://cdn.example.com/avatars/host-b-front.png",
"description": "A man facing the camera in a brightly lit studio, front view.",
"media_type": "image/png"
}
],
"default_source_image_id": "front"
}
}
],
"auto_close": {
"disconnected_timeout_seconds": 60,
"interaction_idle_timeout_seconds": 300
},
"delivery": { "media": { "transport": "trtc" } },
"max_duration_seconds": 300
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'vivix-a1-stream',
idempotency_key: 'avatar-create-123',
region: 'us-west',
session: {mode: 'video_avatar', active_avatar_id: 'host_a', source_image_id: 'front'},
output: {aspect_ratio: '9:16', resolution: '480p'},
pipeline_config: {
tts_config: {
tts_provider: 'qwen-audio-3.0-tts-flash_ws',
tts_voice_id: 'longanhuan_v3.6',
tts_model_id: 'qwen-audio-3.0-tts-flash'
}
},
assets: {
audio: [
{
asset_id: 'welcome_jingle',
url: 'https://cdn.example.com/audio/welcome-jingle.wav',
mime_type: 'audio/wav'
}
],
speech_text: [{asset_id: 'welcome_line', text: 'Welcome back. I saved your place.'}],
visual_prompts: [{asset_id: 'wave_small', prompt: 'smile and give a small wave'}]
},
conversation: {
instructions: 'Answer as a concise livestream host.',
tools: [
{
type: 'function',
name: 'lookup_product',
description: 'Look up product details by product id.',
parameters: {
type: 'object',
properties: {product_id: {type: 'string'}},
required: ['product_id']
}
}
],
response_defaults: {temperature: 0.7, max_output_tokens: 512},
turn_detection: {type: 'server_vad', silence_duration_ms: 500},
input_audio_transcription: {enabled: true, language: 'auto'}
},
avatars: [
{
avatar_id: 'host_a',
instructions: 'You are Host A, a warm livestream host who gives concise product-focused replies.',
visual: {
source_images: [
{
source_image_id: 'front',
url: 'https://cdn.example.com/avatars/host-a-front.png',
description: 'A woman facing the camera in a brightly lit studio, front view.',
media_type: 'image/png'
},
{
source_image_id: 'side',
url: 'https://cdn.example.com/avatars/host-a-side.png',
description: 'The same woman in the same studio, side view.',
media_type: 'image/png'
}
],
default_source_image_id: 'front'
}
},
{
avatar_id: 'host_b',
instructions: 'You are Host B, a calm expert who gives brief technical explanations.',
visual: {
source_images: [
{
source_image_id: 'front',
url: 'https://cdn.example.com/avatars/host-b-front.png',
description: 'A man facing the camera in a brightly lit studio, front view.',
media_type: 'image/png'
}
],
default_source_image_id: 'front'
}
}
],
auto_close: {disconnected_timeout_seconds: 60, interaction_idle_timeout_seconds: 300},
delivery: {media: {transport: 'trtc'}},
max_duration_seconds: 300
})
};
fetch('https://api.vivix.ai/v1/realtime-avatar/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vivix.ai/v1/realtime-avatar/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => 'vivix-a1-stream',
'idempotency_key' => 'avatar-create-123',
'region' => 'us-west',
'session' => [
'mode' => 'video_avatar',
'active_avatar_id' => 'host_a',
'source_image_id' => 'front'
],
'output' => [
'aspect_ratio' => '9:16',
'resolution' => '480p'
],
'pipeline_config' => [
'tts_config' => [
'tts_provider' => 'qwen-audio-3.0-tts-flash_ws',
'tts_voice_id' => 'longanhuan_v3.6',
'tts_model_id' => 'qwen-audio-3.0-tts-flash'
]
],
'assets' => [
'audio' => [
[
'asset_id' => 'welcome_jingle',
'url' => 'https://cdn.example.com/audio/welcome-jingle.wav',
'mime_type' => 'audio/wav'
]
],
'speech_text' => [
[
'asset_id' => 'welcome_line',
'text' => 'Welcome back. I saved your place.'
]
],
'visual_prompts' => [
[
'asset_id' => 'wave_small',
'prompt' => 'smile and give a small wave'
]
]
],
'conversation' => [
'instructions' => 'Answer as a concise livestream host.',
'tools' => [
[
'type' => 'function',
'name' => 'lookup_product',
'description' => 'Look up product details by product id.',
'parameters' => [
'type' => 'object',
'properties' => [
'product_id' => [
'type' => 'string'
]
],
'required' => [
'product_id'
]
]
]
],
'response_defaults' => [
'temperature' => 0.7,
'max_output_tokens' => 512
],
'turn_detection' => [
'type' => 'server_vad',
'silence_duration_ms' => 500
],
'input_audio_transcription' => [
'enabled' => true,
'language' => 'auto'
]
],
'avatars' => [
[
'avatar_id' => 'host_a',
'instructions' => 'You are Host A, a warm livestream host who gives concise product-focused replies.',
'visual' => [
'source_images' => [
[
'source_image_id' => 'front',
'url' => 'https://cdn.example.com/avatars/host-a-front.png',
'description' => 'A woman facing the camera in a brightly lit studio, front view.',
'media_type' => 'image/png'
],
[
'source_image_id' => 'side',
'url' => 'https://cdn.example.com/avatars/host-a-side.png',
'description' => 'The same woman in the same studio, side view.',
'media_type' => 'image/png'
]
],
'default_source_image_id' => 'front'
]
],
[
'avatar_id' => 'host_b',
'instructions' => 'You are Host B, a calm expert who gives brief technical explanations.',
'visual' => [
'source_images' => [
[
'source_image_id' => 'front',
'url' => 'https://cdn.example.com/avatars/host-b-front.png',
'description' => 'A man facing the camera in a brightly lit studio, front view.',
'media_type' => 'image/png'
]
],
'default_source_image_id' => 'front'
]
]
],
'auto_close' => [
'disconnected_timeout_seconds' => 60,
'interaction_idle_timeout_seconds' => 300
],
'delivery' => [
'media' => [
'transport' => 'trtc'
]
],
'max_duration_seconds' => 300
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vivix.ai/v1/realtime-avatar/sessions"
payload := strings.NewReader("{\n \"model\": \"vivix-a1-stream\",\n \"idempotency_key\": \"avatar-create-123\",\n \"region\": \"us-west\",\n \"session\": {\n \"mode\": \"video_avatar\",\n \"active_avatar_id\": \"host_a\",\n \"source_image_id\": \"front\"\n },\n \"output\": {\n \"aspect_ratio\": \"9:16\",\n \"resolution\": \"480p\"\n },\n \"pipeline_config\": {\n \"tts_config\": {\n \"tts_provider\": \"qwen-audio-3.0-tts-flash_ws\",\n \"tts_voice_id\": \"longanhuan_v3.6\",\n \"tts_model_id\": \"qwen-audio-3.0-tts-flash\"\n }\n },\n \"assets\": {\n \"audio\": [\n {\n \"asset_id\": \"welcome_jingle\",\n \"url\": \"https://cdn.example.com/audio/welcome-jingle.wav\",\n \"mime_type\": \"audio/wav\"\n }\n ],\n \"speech_text\": [\n {\n \"asset_id\": \"welcome_line\",\n \"text\": \"Welcome back. I saved your place.\"\n }\n ],\n \"visual_prompts\": [\n {\n \"asset_id\": \"wave_small\",\n \"prompt\": \"smile and give a small wave\"\n }\n ]\n },\n \"conversation\": {\n \"instructions\": \"Answer as a concise livestream host.\",\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"lookup_product\",\n \"description\": \"Look up product details by product id.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"product_id\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"product_id\"\n ]\n }\n }\n ],\n \"response_defaults\": {\n \"temperature\": 0.7,\n \"max_output_tokens\": 512\n },\n \"turn_detection\": {\n \"type\": \"server_vad\",\n \"silence_duration_ms\": 500\n },\n \"input_audio_transcription\": {\n \"enabled\": true,\n \"language\": \"auto\"\n }\n },\n \"avatars\": [\n {\n \"avatar_id\": \"host_a\",\n \"instructions\": \"You are Host A, a warm livestream host who gives concise product-focused replies.\",\n \"visual\": {\n \"source_images\": [\n {\n \"source_image_id\": \"front\",\n \"url\": \"https://cdn.example.com/avatars/host-a-front.png\",\n \"description\": \"A woman facing the camera in a brightly lit studio, front view.\",\n \"media_type\": \"image/png\"\n },\n {\n \"source_image_id\": \"side\",\n \"url\": \"https://cdn.example.com/avatars/host-a-side.png\",\n \"description\": \"The same woman in the same studio, side view.\",\n \"media_type\": \"image/png\"\n }\n ],\n \"default_source_image_id\": \"front\"\n }\n },\n {\n \"avatar_id\": \"host_b\",\n \"instructions\": \"You are Host B, a calm expert who gives brief technical explanations.\",\n \"visual\": {\n \"source_images\": [\n {\n \"source_image_id\": \"front\",\n \"url\": \"https://cdn.example.com/avatars/host-b-front.png\",\n \"description\": \"A man facing the camera in a brightly lit studio, front view.\",\n \"media_type\": \"image/png\"\n }\n ],\n \"default_source_image_id\": \"front\"\n }\n }\n ],\n \"auto_close\": {\n \"disconnected_timeout_seconds\": 60,\n \"interaction_idle_timeout_seconds\": 300\n },\n \"delivery\": {\n \"media\": {\n \"transport\": \"trtc\"\n }\n },\n \"max_duration_seconds\": 300\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.vivix.ai/v1/realtime-avatar/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"vivix-a1-stream\",\n \"idempotency_key\": \"avatar-create-123\",\n \"region\": \"us-west\",\n \"session\": {\n \"mode\": \"video_avatar\",\n \"active_avatar_id\": \"host_a\",\n \"source_image_id\": \"front\"\n },\n \"output\": {\n \"aspect_ratio\": \"9:16\",\n \"resolution\": \"480p\"\n },\n \"pipeline_config\": {\n \"tts_config\": {\n \"tts_provider\": \"qwen-audio-3.0-tts-flash_ws\",\n \"tts_voice_id\": \"longanhuan_v3.6\",\n \"tts_model_id\": \"qwen-audio-3.0-tts-flash\"\n }\n },\n \"assets\": {\n \"audio\": [\n {\n \"asset_id\": \"welcome_jingle\",\n \"url\": \"https://cdn.example.com/audio/welcome-jingle.wav\",\n \"mime_type\": \"audio/wav\"\n }\n ],\n \"speech_text\": [\n {\n \"asset_id\": \"welcome_line\",\n \"text\": \"Welcome back. I saved your place.\"\n }\n ],\n \"visual_prompts\": [\n {\n \"asset_id\": \"wave_small\",\n \"prompt\": \"smile and give a small wave\"\n }\n ]\n },\n \"conversation\": {\n \"instructions\": \"Answer as a concise livestream host.\",\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"lookup_product\",\n \"description\": \"Look up product details by product id.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"product_id\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"product_id\"\n ]\n }\n }\n ],\n \"response_defaults\": {\n \"temperature\": 0.7,\n \"max_output_tokens\": 512\n },\n \"turn_detection\": {\n \"type\": \"server_vad\",\n \"silence_duration_ms\": 500\n },\n \"input_audio_transcription\": {\n \"enabled\": true,\n \"language\": \"auto\"\n }\n },\n \"avatars\": [\n {\n \"avatar_id\": \"host_a\",\n \"instructions\": \"You are Host A, a warm livestream host who gives concise product-focused replies.\",\n \"visual\": {\n \"source_images\": [\n {\n \"source_image_id\": \"front\",\n \"url\": \"https://cdn.example.com/avatars/host-a-front.png\",\n \"description\": \"A woman facing the camera in a brightly lit studio, front view.\",\n \"media_type\": \"image/png\"\n },\n {\n \"source_image_id\": \"side\",\n \"url\": \"https://cdn.example.com/avatars/host-a-side.png\",\n \"description\": \"The same woman in the same studio, side view.\",\n \"media_type\": \"image/png\"\n }\n ],\n \"default_source_image_id\": \"front\"\n }\n },\n {\n \"avatar_id\": \"host_b\",\n \"instructions\": \"You are Host B, a calm expert who gives brief technical explanations.\",\n \"visual\": {\n \"source_images\": [\n {\n \"source_image_id\": \"front\",\n \"url\": \"https://cdn.example.com/avatars/host-b-front.png\",\n \"description\": \"A man facing the camera in a brightly lit studio, front view.\",\n \"media_type\": \"image/png\"\n }\n ],\n \"default_source_image_id\": \"front\"\n }\n }\n ],\n \"auto_close\": {\n \"disconnected_timeout_seconds\": 60,\n \"interaction_idle_timeout_seconds\": 300\n },\n \"delivery\": {\n \"media\": {\n \"transport\": \"trtc\"\n }\n },\n \"max_duration_seconds\": 300\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vivix.ai/v1/realtime-avatar/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"vivix-a1-stream\",\n \"idempotency_key\": \"avatar-create-123\",\n \"region\": \"us-west\",\n \"session\": {\n \"mode\": \"video_avatar\",\n \"active_avatar_id\": \"host_a\",\n \"source_image_id\": \"front\"\n },\n \"output\": {\n \"aspect_ratio\": \"9:16\",\n \"resolution\": \"480p\"\n },\n \"pipeline_config\": {\n \"tts_config\": {\n \"tts_provider\": \"qwen-audio-3.0-tts-flash_ws\",\n \"tts_voice_id\": \"longanhuan_v3.6\",\n \"tts_model_id\": \"qwen-audio-3.0-tts-flash\"\n }\n },\n \"assets\": {\n \"audio\": [\n {\n \"asset_id\": \"welcome_jingle\",\n \"url\": \"https://cdn.example.com/audio/welcome-jingle.wav\",\n \"mime_type\": \"audio/wav\"\n }\n ],\n \"speech_text\": [\n {\n \"asset_id\": \"welcome_line\",\n \"text\": \"Welcome back. I saved your place.\"\n }\n ],\n \"visual_prompts\": [\n {\n \"asset_id\": \"wave_small\",\n \"prompt\": \"smile and give a small wave\"\n }\n ]\n },\n \"conversation\": {\n \"instructions\": \"Answer as a concise livestream host.\",\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"lookup_product\",\n \"description\": \"Look up product details by product id.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"product_id\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"product_id\"\n ]\n }\n }\n ],\n \"response_defaults\": {\n \"temperature\": 0.7,\n \"max_output_tokens\": 512\n },\n \"turn_detection\": {\n \"type\": \"server_vad\",\n \"silence_duration_ms\": 500\n },\n \"input_audio_transcription\": {\n \"enabled\": true,\n \"language\": \"auto\"\n }\n },\n \"avatars\": [\n {\n \"avatar_id\": \"host_a\",\n \"instructions\": \"You are Host A, a warm livestream host who gives concise product-focused replies.\",\n \"visual\": {\n \"source_images\": [\n {\n \"source_image_id\": \"front\",\n \"url\": \"https://cdn.example.com/avatars/host-a-front.png\",\n \"description\": \"A woman facing the camera in a brightly lit studio, front view.\",\n \"media_type\": \"image/png\"\n },\n {\n \"source_image_id\": \"side\",\n \"url\": \"https://cdn.example.com/avatars/host-a-side.png\",\n \"description\": \"The same woman in the same studio, side view.\",\n \"media_type\": \"image/png\"\n }\n ],\n \"default_source_image_id\": \"front\"\n }\n },\n {\n \"avatar_id\": \"host_b\",\n \"instructions\": \"You are Host B, a calm expert who gives brief technical explanations.\",\n \"visual\": {\n \"source_images\": [\n {\n \"source_image_id\": \"front\",\n \"url\": \"https://cdn.example.com/avatars/host-b-front.png\",\n \"description\": \"A man facing the camera in a brightly lit studio, front view.\",\n \"media_type\": \"image/png\"\n }\n ],\n \"default_source_image_id\": \"front\"\n }\n }\n ],\n \"auto_close\": {\n \"disconnected_timeout_seconds\": 60,\n \"interaction_idle_timeout_seconds\": 300\n },\n \"delivery\": {\n \"media\": {\n \"transport\": \"trtc\"\n }\n },\n \"max_duration_seconds\": 300\n}"
response = http.request(request)
puts response.read_body{
"code": 0,
"message": "success",
"data": {
"session_id": "avatar-session-123",
"status": "active",
"auto_close": {
"disconnected_timeout_seconds": 60,
"interaction_idle_timeout_seconds": 300
},
"region": "us-west",
"session": {
"mode": "video_avatar",
"active_avatar_id": "host_a",
"source_image_id": "front"
},
"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
},
"assets": {
"audio": [
{
"asset_id": "welcome_jingle",
"url": "https://cdn.example.com/audio/welcome-jingle.wav",
"mime_type": "audio/wav"
}
],
"speech_text": [
{
"asset_id": "welcome_line",
"text": "Welcome back. I saved your place."
}
],
"visual_prompts": [
{
"asset_id": "wave_small",
"prompt": "smile and give a small wave"
}
]
},
"conversation": {
"instructions": "Answer as a concise livestream host.",
"tools": [
{
"type": "function",
"name": "lookup_product",
"description": "Look up product details by product id.",
"parameters": {
"type": "object",
"properties": {
"product_id": {
"type": "string"
}
},
"required": [
"product_id"
]
}
}
],
"response_defaults": {
"temperature": 0.7,
"max_output_tokens": 512
},
"turn_detection": {
"type": "server_vad",
"silence_duration_ms": 500
},
"input_audio_transcription": {
"enabled": true,
"language": "auto"
}
},
"avatars": [
{
"avatar_id": "host_a",
"instructions": "You are Host A, a warm livestream host who gives concise product-focused replies.",
"visual": {
"source_images": [
{
"source_image_id": "front",
"url": "https://cdn.example.com/avatars/host-a-front.png",
"description": "A woman facing the camera in a brightly lit studio, front view.",
"media_type": "image/png"
},
{
"source_image_id": "side",
"url": "https://cdn.example.com/avatars/host-a-side.png",
"description": "The same woman in the same studio, side view.",
"media_type": "image/png"
}
],
"default_source_image_id": "front"
}
},
{
"avatar_id": "host_b",
"instructions": "You are Host B, a calm expert who gives brief technical explanations.",
"visual": {
"source_images": [
{
"source_image_id": "front",
"url": "https://cdn.example.com/avatars/host-b-front.png",
"description": "A man facing the camera in a brightly lit studio, front view.",
"media_type": "image/png"
}
],
"default_source_image_id": "front"
}
}
],
"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",
"expires_at": "2026-07-16T10:05:00Z"
}
}Sessions
Create Session
Creates a Streaming Avatar session, registers reusable script assets and the avatars that can appear in the session, and returns the WSS control channel plus media connection details.
After the call returns, save session_id, control.url, control.client_secret, delivery.media, and the effective session.mode / active_avatar_id / source_image_id resolved by the server.
Start from a saved character. If you already have a character_id, use Create Session from Character instead of sending the full configuration again. Save characters in Characters.
POST
/
v1
/
realtime-avatar
/
sessions
Create Session
curl --request POST \
--url https://api.vivix.ai/v1/realtime-avatar/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "vivix-a1-stream",
"idempotency_key": "avatar-create-123",
"region": "us-west",
"session": {
"mode": "video_avatar",
"active_avatar_id": "host_a",
"source_image_id": "front"
},
"output": {
"aspect_ratio": "9:16",
"resolution": "480p"
},
"pipeline_config": {
"tts_config": {
"tts_provider": "qwen-audio-3.0-tts-flash_ws",
"tts_voice_id": "longanhuan_v3.6",
"tts_model_id": "qwen-audio-3.0-tts-flash"
}
},
"assets": {
"audio": [
{
"asset_id": "welcome_jingle",
"url": "https://cdn.example.com/audio/welcome-jingle.wav",
"mime_type": "audio/wav"
}
],
"speech_text": [
{
"asset_id": "welcome_line",
"text": "Welcome back. I saved your place."
}
],
"visual_prompts": [
{
"asset_id": "wave_small",
"prompt": "smile and give a small wave"
}
]
},
"conversation": {
"instructions": "Answer as a concise livestream host.",
"tools": [
{
"type": "function",
"name": "lookup_product",
"description": "Look up product details by product id.",
"parameters": {
"type": "object",
"properties": {
"product_id": {
"type": "string"
}
},
"required": [
"product_id"
]
}
}
],
"response_defaults": {
"temperature": 0.7,
"max_output_tokens": 512
},
"turn_detection": {
"type": "server_vad",
"silence_duration_ms": 500
},
"input_audio_transcription": {
"enabled": true,
"language": "auto"
}
},
"avatars": [
{
"avatar_id": "host_a",
"instructions": "You are Host A, a warm livestream host who gives concise product-focused replies.",
"visual": {
"source_images": [
{
"source_image_id": "front",
"url": "https://cdn.example.com/avatars/host-a-front.png",
"description": "A woman facing the camera in a brightly lit studio, front view.",
"media_type": "image/png"
},
{
"source_image_id": "side",
"url": "https://cdn.example.com/avatars/host-a-side.png",
"description": "The same woman in the same studio, side view.",
"media_type": "image/png"
}
],
"default_source_image_id": "front"
}
},
{
"avatar_id": "host_b",
"instructions": "You are Host B, a calm expert who gives brief technical explanations.",
"visual": {
"source_images": [
{
"source_image_id": "front",
"url": "https://cdn.example.com/avatars/host-b-front.png",
"description": "A man facing the camera in a brightly lit studio, front view.",
"media_type": "image/png"
}
],
"default_source_image_id": "front"
}
}
],
"auto_close": {
"disconnected_timeout_seconds": 60,
"interaction_idle_timeout_seconds": 300
},
"delivery": {
"media": {
"transport": "trtc"
}
},
"max_duration_seconds": 300
}
'import requests
url = "https://api.vivix.ai/v1/realtime-avatar/sessions"
payload = {
"model": "vivix-a1-stream",
"idempotency_key": "avatar-create-123",
"region": "us-west",
"session": {
"mode": "video_avatar",
"active_avatar_id": "host_a",
"source_image_id": "front"
},
"output": {
"aspect_ratio": "9:16",
"resolution": "480p"
},
"pipeline_config": { "tts_config": {
"tts_provider": "qwen-audio-3.0-tts-flash_ws",
"tts_voice_id": "longanhuan_v3.6",
"tts_model_id": "qwen-audio-3.0-tts-flash"
} },
"assets": {
"audio": [
{
"asset_id": "welcome_jingle",
"url": "https://cdn.example.com/audio/welcome-jingle.wav",
"mime_type": "audio/wav"
}
],
"speech_text": [
{
"asset_id": "welcome_line",
"text": "Welcome back. I saved your place."
}
],
"visual_prompts": [
{
"asset_id": "wave_small",
"prompt": "smile and give a small wave"
}
]
},
"conversation": {
"instructions": "Answer as a concise livestream host.",
"tools": [
{
"type": "function",
"name": "lookup_product",
"description": "Look up product details by product id.",
"parameters": {
"type": "object",
"properties": { "product_id": { "type": "string" } },
"required": ["product_id"]
}
}
],
"response_defaults": {
"temperature": 0.7,
"max_output_tokens": 512
},
"turn_detection": {
"type": "server_vad",
"silence_duration_ms": 500
},
"input_audio_transcription": {
"enabled": True,
"language": "auto"
}
},
"avatars": [
{
"avatar_id": "host_a",
"instructions": "You are Host A, a warm livestream host who gives concise product-focused replies.",
"visual": {
"source_images": [
{
"source_image_id": "front",
"url": "https://cdn.example.com/avatars/host-a-front.png",
"description": "A woman facing the camera in a brightly lit studio, front view.",
"media_type": "image/png"
},
{
"source_image_id": "side",
"url": "https://cdn.example.com/avatars/host-a-side.png",
"description": "The same woman in the same studio, side view.",
"media_type": "image/png"
}
],
"default_source_image_id": "front"
}
},
{
"avatar_id": "host_b",
"instructions": "You are Host B, a calm expert who gives brief technical explanations.",
"visual": {
"source_images": [
{
"source_image_id": "front",
"url": "https://cdn.example.com/avatars/host-b-front.png",
"description": "A man facing the camera in a brightly lit studio, front view.",
"media_type": "image/png"
}
],
"default_source_image_id": "front"
}
}
],
"auto_close": {
"disconnected_timeout_seconds": 60,
"interaction_idle_timeout_seconds": 300
},
"delivery": { "media": { "transport": "trtc" } },
"max_duration_seconds": 300
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'vivix-a1-stream',
idempotency_key: 'avatar-create-123',
region: 'us-west',
session: {mode: 'video_avatar', active_avatar_id: 'host_a', source_image_id: 'front'},
output: {aspect_ratio: '9:16', resolution: '480p'},
pipeline_config: {
tts_config: {
tts_provider: 'qwen-audio-3.0-tts-flash_ws',
tts_voice_id: 'longanhuan_v3.6',
tts_model_id: 'qwen-audio-3.0-tts-flash'
}
},
assets: {
audio: [
{
asset_id: 'welcome_jingle',
url: 'https://cdn.example.com/audio/welcome-jingle.wav',
mime_type: 'audio/wav'
}
],
speech_text: [{asset_id: 'welcome_line', text: 'Welcome back. I saved your place.'}],
visual_prompts: [{asset_id: 'wave_small', prompt: 'smile and give a small wave'}]
},
conversation: {
instructions: 'Answer as a concise livestream host.',
tools: [
{
type: 'function',
name: 'lookup_product',
description: 'Look up product details by product id.',
parameters: {
type: 'object',
properties: {product_id: {type: 'string'}},
required: ['product_id']
}
}
],
response_defaults: {temperature: 0.7, max_output_tokens: 512},
turn_detection: {type: 'server_vad', silence_duration_ms: 500},
input_audio_transcription: {enabled: true, language: 'auto'}
},
avatars: [
{
avatar_id: 'host_a',
instructions: 'You are Host A, a warm livestream host who gives concise product-focused replies.',
visual: {
source_images: [
{
source_image_id: 'front',
url: 'https://cdn.example.com/avatars/host-a-front.png',
description: 'A woman facing the camera in a brightly lit studio, front view.',
media_type: 'image/png'
},
{
source_image_id: 'side',
url: 'https://cdn.example.com/avatars/host-a-side.png',
description: 'The same woman in the same studio, side view.',
media_type: 'image/png'
}
],
default_source_image_id: 'front'
}
},
{
avatar_id: 'host_b',
instructions: 'You are Host B, a calm expert who gives brief technical explanations.',
visual: {
source_images: [
{
source_image_id: 'front',
url: 'https://cdn.example.com/avatars/host-b-front.png',
description: 'A man facing the camera in a brightly lit studio, front view.',
media_type: 'image/png'
}
],
default_source_image_id: 'front'
}
}
],
auto_close: {disconnected_timeout_seconds: 60, interaction_idle_timeout_seconds: 300},
delivery: {media: {transport: 'trtc'}},
max_duration_seconds: 300
})
};
fetch('https://api.vivix.ai/v1/realtime-avatar/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.vivix.ai/v1/realtime-avatar/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => 'vivix-a1-stream',
'idempotency_key' => 'avatar-create-123',
'region' => 'us-west',
'session' => [
'mode' => 'video_avatar',
'active_avatar_id' => 'host_a',
'source_image_id' => 'front'
],
'output' => [
'aspect_ratio' => '9:16',
'resolution' => '480p'
],
'pipeline_config' => [
'tts_config' => [
'tts_provider' => 'qwen-audio-3.0-tts-flash_ws',
'tts_voice_id' => 'longanhuan_v3.6',
'tts_model_id' => 'qwen-audio-3.0-tts-flash'
]
],
'assets' => [
'audio' => [
[
'asset_id' => 'welcome_jingle',
'url' => 'https://cdn.example.com/audio/welcome-jingle.wav',
'mime_type' => 'audio/wav'
]
],
'speech_text' => [
[
'asset_id' => 'welcome_line',
'text' => 'Welcome back. I saved your place.'
]
],
'visual_prompts' => [
[
'asset_id' => 'wave_small',
'prompt' => 'smile and give a small wave'
]
]
],
'conversation' => [
'instructions' => 'Answer as a concise livestream host.',
'tools' => [
[
'type' => 'function',
'name' => 'lookup_product',
'description' => 'Look up product details by product id.',
'parameters' => [
'type' => 'object',
'properties' => [
'product_id' => [
'type' => 'string'
]
],
'required' => [
'product_id'
]
]
]
],
'response_defaults' => [
'temperature' => 0.7,
'max_output_tokens' => 512
],
'turn_detection' => [
'type' => 'server_vad',
'silence_duration_ms' => 500
],
'input_audio_transcription' => [
'enabled' => true,
'language' => 'auto'
]
],
'avatars' => [
[
'avatar_id' => 'host_a',
'instructions' => 'You are Host A, a warm livestream host who gives concise product-focused replies.',
'visual' => [
'source_images' => [
[
'source_image_id' => 'front',
'url' => 'https://cdn.example.com/avatars/host-a-front.png',
'description' => 'A woman facing the camera in a brightly lit studio, front view.',
'media_type' => 'image/png'
],
[
'source_image_id' => 'side',
'url' => 'https://cdn.example.com/avatars/host-a-side.png',
'description' => 'The same woman in the same studio, side view.',
'media_type' => 'image/png'
]
],
'default_source_image_id' => 'front'
]
],
[
'avatar_id' => 'host_b',
'instructions' => 'You are Host B, a calm expert who gives brief technical explanations.',
'visual' => [
'source_images' => [
[
'source_image_id' => 'front',
'url' => 'https://cdn.example.com/avatars/host-b-front.png',
'description' => 'A man facing the camera in a brightly lit studio, front view.',
'media_type' => 'image/png'
]
],
'default_source_image_id' => 'front'
]
]
],
'auto_close' => [
'disconnected_timeout_seconds' => 60,
'interaction_idle_timeout_seconds' => 300
],
'delivery' => [
'media' => [
'transport' => 'trtc'
]
],
'max_duration_seconds' => 300
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vivix.ai/v1/realtime-avatar/sessions"
payload := strings.NewReader("{\n \"model\": \"vivix-a1-stream\",\n \"idempotency_key\": \"avatar-create-123\",\n \"region\": \"us-west\",\n \"session\": {\n \"mode\": \"video_avatar\",\n \"active_avatar_id\": \"host_a\",\n \"source_image_id\": \"front\"\n },\n \"output\": {\n \"aspect_ratio\": \"9:16\",\n \"resolution\": \"480p\"\n },\n \"pipeline_config\": {\n \"tts_config\": {\n \"tts_provider\": \"qwen-audio-3.0-tts-flash_ws\",\n \"tts_voice_id\": \"longanhuan_v3.6\",\n \"tts_model_id\": \"qwen-audio-3.0-tts-flash\"\n }\n },\n \"assets\": {\n \"audio\": [\n {\n \"asset_id\": \"welcome_jingle\",\n \"url\": \"https://cdn.example.com/audio/welcome-jingle.wav\",\n \"mime_type\": \"audio/wav\"\n }\n ],\n \"speech_text\": [\n {\n \"asset_id\": \"welcome_line\",\n \"text\": \"Welcome back. I saved your place.\"\n }\n ],\n \"visual_prompts\": [\n {\n \"asset_id\": \"wave_small\",\n \"prompt\": \"smile and give a small wave\"\n }\n ]\n },\n \"conversation\": {\n \"instructions\": \"Answer as a concise livestream host.\",\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"lookup_product\",\n \"description\": \"Look up product details by product id.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"product_id\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"product_id\"\n ]\n }\n }\n ],\n \"response_defaults\": {\n \"temperature\": 0.7,\n \"max_output_tokens\": 512\n },\n \"turn_detection\": {\n \"type\": \"server_vad\",\n \"silence_duration_ms\": 500\n },\n \"input_audio_transcription\": {\n \"enabled\": true,\n \"language\": \"auto\"\n }\n },\n \"avatars\": [\n {\n \"avatar_id\": \"host_a\",\n \"instructions\": \"You are Host A, a warm livestream host who gives concise product-focused replies.\",\n \"visual\": {\n \"source_images\": [\n {\n \"source_image_id\": \"front\",\n \"url\": \"https://cdn.example.com/avatars/host-a-front.png\",\n \"description\": \"A woman facing the camera in a brightly lit studio, front view.\",\n \"media_type\": \"image/png\"\n },\n {\n \"source_image_id\": \"side\",\n \"url\": \"https://cdn.example.com/avatars/host-a-side.png\",\n \"description\": \"The same woman in the same studio, side view.\",\n \"media_type\": \"image/png\"\n }\n ],\n \"default_source_image_id\": \"front\"\n }\n },\n {\n \"avatar_id\": \"host_b\",\n \"instructions\": \"You are Host B, a calm expert who gives brief technical explanations.\",\n \"visual\": {\n \"source_images\": [\n {\n \"source_image_id\": \"front\",\n \"url\": \"https://cdn.example.com/avatars/host-b-front.png\",\n \"description\": \"A man facing the camera in a brightly lit studio, front view.\",\n \"media_type\": \"image/png\"\n }\n ],\n \"default_source_image_id\": \"front\"\n }\n }\n ],\n \"auto_close\": {\n \"disconnected_timeout_seconds\": 60,\n \"interaction_idle_timeout_seconds\": 300\n },\n \"delivery\": {\n \"media\": {\n \"transport\": \"trtc\"\n }\n },\n \"max_duration_seconds\": 300\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.vivix.ai/v1/realtime-avatar/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"vivix-a1-stream\",\n \"idempotency_key\": \"avatar-create-123\",\n \"region\": \"us-west\",\n \"session\": {\n \"mode\": \"video_avatar\",\n \"active_avatar_id\": \"host_a\",\n \"source_image_id\": \"front\"\n },\n \"output\": {\n \"aspect_ratio\": \"9:16\",\n \"resolution\": \"480p\"\n },\n \"pipeline_config\": {\n \"tts_config\": {\n \"tts_provider\": \"qwen-audio-3.0-tts-flash_ws\",\n \"tts_voice_id\": \"longanhuan_v3.6\",\n \"tts_model_id\": \"qwen-audio-3.0-tts-flash\"\n }\n },\n \"assets\": {\n \"audio\": [\n {\n \"asset_id\": \"welcome_jingle\",\n \"url\": \"https://cdn.example.com/audio/welcome-jingle.wav\",\n \"mime_type\": \"audio/wav\"\n }\n ],\n \"speech_text\": [\n {\n \"asset_id\": \"welcome_line\",\n \"text\": \"Welcome back. I saved your place.\"\n }\n ],\n \"visual_prompts\": [\n {\n \"asset_id\": \"wave_small\",\n \"prompt\": \"smile and give a small wave\"\n }\n ]\n },\n \"conversation\": {\n \"instructions\": \"Answer as a concise livestream host.\",\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"lookup_product\",\n \"description\": \"Look up product details by product id.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"product_id\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"product_id\"\n ]\n }\n }\n ],\n \"response_defaults\": {\n \"temperature\": 0.7,\n \"max_output_tokens\": 512\n },\n \"turn_detection\": {\n \"type\": \"server_vad\",\n \"silence_duration_ms\": 500\n },\n \"input_audio_transcription\": {\n \"enabled\": true,\n \"language\": \"auto\"\n }\n },\n \"avatars\": [\n {\n \"avatar_id\": \"host_a\",\n \"instructions\": \"You are Host A, a warm livestream host who gives concise product-focused replies.\",\n \"visual\": {\n \"source_images\": [\n {\n \"source_image_id\": \"front\",\n \"url\": \"https://cdn.example.com/avatars/host-a-front.png\",\n \"description\": \"A woman facing the camera in a brightly lit studio, front view.\",\n \"media_type\": \"image/png\"\n },\n {\n \"source_image_id\": \"side\",\n \"url\": \"https://cdn.example.com/avatars/host-a-side.png\",\n \"description\": \"The same woman in the same studio, side view.\",\n \"media_type\": \"image/png\"\n }\n ],\n \"default_source_image_id\": \"front\"\n }\n },\n {\n \"avatar_id\": \"host_b\",\n \"instructions\": \"You are Host B, a calm expert who gives brief technical explanations.\",\n \"visual\": {\n \"source_images\": [\n {\n \"source_image_id\": \"front\",\n \"url\": \"https://cdn.example.com/avatars/host-b-front.png\",\n \"description\": \"A man facing the camera in a brightly lit studio, front view.\",\n \"media_type\": \"image/png\"\n }\n ],\n \"default_source_image_id\": \"front\"\n }\n }\n ],\n \"auto_close\": {\n \"disconnected_timeout_seconds\": 60,\n \"interaction_idle_timeout_seconds\": 300\n },\n \"delivery\": {\n \"media\": {\n \"transport\": \"trtc\"\n }\n },\n \"max_duration_seconds\": 300\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.vivix.ai/v1/realtime-avatar/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"vivix-a1-stream\",\n \"idempotency_key\": \"avatar-create-123\",\n \"region\": \"us-west\",\n \"session\": {\n \"mode\": \"video_avatar\",\n \"active_avatar_id\": \"host_a\",\n \"source_image_id\": \"front\"\n },\n \"output\": {\n \"aspect_ratio\": \"9:16\",\n \"resolution\": \"480p\"\n },\n \"pipeline_config\": {\n \"tts_config\": {\n \"tts_provider\": \"qwen-audio-3.0-tts-flash_ws\",\n \"tts_voice_id\": \"longanhuan_v3.6\",\n \"tts_model_id\": \"qwen-audio-3.0-tts-flash\"\n }\n },\n \"assets\": {\n \"audio\": [\n {\n \"asset_id\": \"welcome_jingle\",\n \"url\": \"https://cdn.example.com/audio/welcome-jingle.wav\",\n \"mime_type\": \"audio/wav\"\n }\n ],\n \"speech_text\": [\n {\n \"asset_id\": \"welcome_line\",\n \"text\": \"Welcome back. I saved your place.\"\n }\n ],\n \"visual_prompts\": [\n {\n \"asset_id\": \"wave_small\",\n \"prompt\": \"smile and give a small wave\"\n }\n ]\n },\n \"conversation\": {\n \"instructions\": \"Answer as a concise livestream host.\",\n \"tools\": [\n {\n \"type\": \"function\",\n \"name\": \"lookup_product\",\n \"description\": \"Look up product details by product id.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"product_id\": {\n \"type\": \"string\"\n }\n },\n \"required\": [\n \"product_id\"\n ]\n }\n }\n ],\n \"response_defaults\": {\n \"temperature\": 0.7,\n \"max_output_tokens\": 512\n },\n \"turn_detection\": {\n \"type\": \"server_vad\",\n \"silence_duration_ms\": 500\n },\n \"input_audio_transcription\": {\n \"enabled\": true,\n \"language\": \"auto\"\n }\n },\n \"avatars\": [\n {\n \"avatar_id\": \"host_a\",\n \"instructions\": \"You are Host A, a warm livestream host who gives concise product-focused replies.\",\n \"visual\": {\n \"source_images\": [\n {\n \"source_image_id\": \"front\",\n \"url\": \"https://cdn.example.com/avatars/host-a-front.png\",\n \"description\": \"A woman facing the camera in a brightly lit studio, front view.\",\n \"media_type\": \"image/png\"\n },\n {\n \"source_image_id\": \"side\",\n \"url\": \"https://cdn.example.com/avatars/host-a-side.png\",\n \"description\": \"The same woman in the same studio, side view.\",\n \"media_type\": \"image/png\"\n }\n ],\n \"default_source_image_id\": \"front\"\n }\n },\n {\n \"avatar_id\": \"host_b\",\n \"instructions\": \"You are Host B, a calm expert who gives brief technical explanations.\",\n \"visual\": {\n \"source_images\": [\n {\n \"source_image_id\": \"front\",\n \"url\": \"https://cdn.example.com/avatars/host-b-front.png\",\n \"description\": \"A man facing the camera in a brightly lit studio, front view.\",\n \"media_type\": \"image/png\"\n }\n ],\n \"default_source_image_id\": \"front\"\n }\n }\n ],\n \"auto_close\": {\n \"disconnected_timeout_seconds\": 60,\n \"interaction_idle_timeout_seconds\": 300\n },\n \"delivery\": {\n \"media\": {\n \"transport\": \"trtc\"\n }\n },\n \"max_duration_seconds\": 300\n}"
response = http.request(request)
puts response.read_body{
"code": 0,
"message": "success",
"data": {
"session_id": "avatar-session-123",
"status": "active",
"auto_close": {
"disconnected_timeout_seconds": 60,
"interaction_idle_timeout_seconds": 300
},
"region": "us-west",
"session": {
"mode": "video_avatar",
"active_avatar_id": "host_a",
"source_image_id": "front"
},
"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
},
"assets": {
"audio": [
{
"asset_id": "welcome_jingle",
"url": "https://cdn.example.com/audio/welcome-jingle.wav",
"mime_type": "audio/wav"
}
],
"speech_text": [
{
"asset_id": "welcome_line",
"text": "Welcome back. I saved your place."
}
],
"visual_prompts": [
{
"asset_id": "wave_small",
"prompt": "smile and give a small wave"
}
]
},
"conversation": {
"instructions": "Answer as a concise livestream host.",
"tools": [
{
"type": "function",
"name": "lookup_product",
"description": "Look up product details by product id.",
"parameters": {
"type": "object",
"properties": {
"product_id": {
"type": "string"
}
},
"required": [
"product_id"
]
}
}
],
"response_defaults": {
"temperature": 0.7,
"max_output_tokens": 512
},
"turn_detection": {
"type": "server_vad",
"silence_duration_ms": 500
},
"input_audio_transcription": {
"enabled": true,
"language": "auto"
}
},
"avatars": [
{
"avatar_id": "host_a",
"instructions": "You are Host A, a warm livestream host who gives concise product-focused replies.",
"visual": {
"source_images": [
{
"source_image_id": "front",
"url": "https://cdn.example.com/avatars/host-a-front.png",
"description": "A woman facing the camera in a brightly lit studio, front view.",
"media_type": "image/png"
},
{
"source_image_id": "side",
"url": "https://cdn.example.com/avatars/host-a-side.png",
"description": "The same woman in the same studio, side view.",
"media_type": "image/png"
}
],
"default_source_image_id": "front"
}
},
{
"avatar_id": "host_b",
"instructions": "You are Host B, a calm expert who gives brief technical explanations.",
"visual": {
"source_images": [
{
"source_image_id": "front",
"url": "https://cdn.example.com/avatars/host-b-front.png",
"description": "A man facing the camera in a brightly lit studio, front view.",
"media_type": "image/png"
}
],
"default_source_image_id": "front"
}
}
],
"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",
"expires_at": "2026-07-16T10:05:00Z"
}
}Connect to the control channel
Connect to the control channel
A browser must not open
control.url without a token. Append the credential as the token query parameter:const controlUrl = new URL(session.control.url);
controlUrl.searchParams.set("token", session.control.client_secret);
const ws = new WebSocket(controlUrl.toString());
URL.searchParams preserves the existing session_id and encodes the credential. The query parameter name must be token, not client_secret. Server-side WebSocket clients may instead send Authorization: Bearer CONTROL_CLIENT_SECRET. Keep the credential and the complete URL out of logs.Automatic closure
Automatic closure
Direct Create Session accepts an optional top-level
auto_close object. The response returns the effective rules under the same name.An explicit nonzero value cannot exceed the effective maximum session duration. See Automatic session closure for setup and closing conditions.Errors
Errors
Error responses use the same
{code, message, data} envelope; a non-zero code identifies the error.| Case | Error code |
|---|---|
| Create request has no avatars, duplicate avatar ids, incomplete avatar definitions, or an invalid initial session state | 30004 invalid argument |
| The requested model, output, or maximum duration is not supported | 30004 invalid argument |
| An auto-close timeout is outside its allowed range or exceeds the maximum session duration | 30004 invalid argument |
| The session id does not exist or the realtime URL has expired | 20005 not found |
| The API key is missing or invalid | 10001 missing api key or 10003 invalid api key |
| Workspace billing is inactive or the balance is insufficient | 10004 workspace billing is not active or 10005 insufficient workspace balance |
| The request exceeded the API key rate limit (HTTP 429; 60 requests/min per key by default, configurable; the response includes a Retry-After header). Back off exponentially and honor Retry-After | 10008 API rate limit exceeded |
| The number of concurrently open sessions for this workspace reached its limit (HTTP 429, no Retry-After). Call List Sessions to find unclosed sessions and Close the ones that already ended but still hold quota, then retry; if your business needs a higher concurrency limit, contact sales to adjust the workspace quota | 30006 workspace concurrency limit exceeded |
| Platform-side model capacity is currently insufficient (HTTP 429, no Retry-After). This is not a quota issue: retry after a short backoff, and contact us if it persists so capacity can be extended | 30008 model resource capacity exceeded |
| This API key has not been granted access to the requested model or API. Confirm in the console that the app has the corresponding model/API permission enabled, ask your account owner to enable access, then retry | 10009 api access denied |
Authorizations
Your Vivix API key. Keep it on your server.
Body
application/json
Use vivix-a1-stream. A lightweight variant vivix-a1-stream-lite is also available.
Create-time avatar video output settings for the session. Required for video_avatar mode and applied when session.mode is video_avatar; ignored in text_chat mode.
Show child attributes
Show child attributes
Session-local avatars available for conversation and rendering. A full create request requires a nonempty list with unique avatar_id values. An avatar used for video rendering needs a visual definition with a usable source image; a text-only avatar does not. Configure the session-wide voice in pipeline_config.tts_config.
Show child attributes
Show child attributes
Client-generated key used to prevent duplicate session allocation when a create request is retried. On a 429/5xx/timeout, retry the create call with the same idempotency_key; it is safe and will not allocate a duplicate session.
Optional deployment region hint. Returned back on the session object; may be empty if not provided. It does not currently affect scheduling or guarantee data residency.
Initial mutable session state for mode, active avatar, and optional video source image. Use session.update to change these values after the session starts.
Show child attributes
Show child attributes
Session-scoped pipeline configuration. For normal generated speech, provide tts_config here with a non-empty tts_voice_id; tts_provider and tts_model_id may be omitted and then default to the Qwen Audio pair. It applies to every avatar and cannot be changed after session creation. See Speech recognition configuration.
Show child attributes
Show child attributes
Initial conversational defaults such as instructions, tools, turn handling, and response defaults.
Show child attributes
Show child attributes
Session-scoped reusable assets for response.script. Asset ids must be unique across audio, speech_text, and visual_prompts. Avatar source images stay under avatars[].visual.source_images. On the REST side the visual prompt text field is prompt; on the WSS asset.add side the same asset uses text — the two shapes differ.
Show child attributes
Show child attributes
Media delivery settings used when session.mode is video_avatar. If omitted, the media transport defaults to TRTC. It is not used for text_chat.
Show child attributes
Show child attributes
Requested maximum session duration in seconds. If omitted, the service-configured default applies. An explicit value must be greater than 3 (minimum 4); 0 is rejected. The service may still close the session for account limits, idle timeout, failures, or maintenance.
Automatic close policy fixed when the session is created. The response returns the effective values after platform defaults are applied.
Show child attributes
Show child attributes
on or off. Send off to disable recording.