Live Avatar API

x-api-key: sk_your_api_key
Content-Type: application/json

# Use an id from workspaces[].id, not a workspace name or URL slug.
export UNCAGED_WORKSPACE_ID="your_workspace_id"

curl --fail-with-body "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-character-voices/presets" \
  -H "x-api-key: $UNCAGED_API_KEY"

# Select voices[].voiceId from the returned catalog.
export UNCAGED_VOICE_ID="voice_id_from_catalog"

// avatar-api.js, server only, Node.js 20+
const BASE = 'https://api.sequencer.media/v1';
const key = process.env.UNCAGED_API_KEY;
const workspace = process.env.UNCAGED_WORKSPACE_ID;
const character = process.env.UNCAGED_CHARACTER_ID;
if (!key || !workspace || !character) throw new Error('Missing avatar configuration');
const wsPath = '/workspaces/' + encodeURIComponent(workspace);

export async function avatarApi(path, { method = 'GET', body, origin } = {}) {
  const response = await fetch(BASE + wsPath + path, {
    method,
    headers: {
      'x-api-key': key,
      'Content-Type': 'application/json',
      // For sessions, set this to your configured web app origin.
      ...(origin ? { Origin: origin } : {})
    },
    ...(body ? { body: JSON.stringify(body) } : {})
  });
  const data = await response.json();
  if (!response.ok) {
    const error = new Error(data.error || 'Avatar API request failed');
    error.status = response.status;
    error.retryAfter = response.headers.get('Retry-After');
    throw error;
  }
  return data;
}

export function startAvatar(userId, channels, conversationHistory = [], startToken) {
  return avatarApi('/live-characters/' + encodeURIComponent(character) + '/sessions', {
    method: 'POST',
    origin: process.env.APP_ORIGIN, // e.g. https://your-app.example
    body: {
      launchMode: 'webrtc', sessionMode: 'conversation',
      channels, endUserId: userId, maxSessionSeconds: 300,
      saveHistory: false,
      ...(conversationHistory.length ? { conversationHistory } : {}),
      ...(startToken ? { startToken } : {})
    }
  });
}

export function endAvatar(sessionId) {
  return avatarApi('/live-character-sessions/' + encodeURIComponent(sessionId) + '/end', {
    method: 'POST', body: { reason: 'USER_CLOSED' }
  });
}

curl --fail-with-body -X POST \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-characters" \
  -H "x-api-key: $UNCAGED_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Avery\",
    \"avatarImageUrl\": \"https://your-cdn.example/avery.jpg\",
    \"voiceSource\": \"preset\",
    \"providerVoiceId\": \"$UNCAGED_VOICE_ID\",
    \"systemPrompt\": \"You are Avery, a friendly, playful guide. Speak casually and keep replies to one or two sentences.\",
    \"runtimeProvider\": \"sequencer\",
    \"animaMode\": \"fast\",
    \"language\": \"en\",
    \"maxSessionMinutes\": 5
  }"

# Save liveCharacter.id from the response.
export UNCAGED_CHARACTER_ID="your_character_id"

curl --fail-with-body "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-character-voices/presets" \
  -H "x-api-key: $UNCAGED_API_KEY"

# Returns audio bytes. Save and listen locally.
curl --fail-with-body \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-character-voices/presets/$UNCAGED_VOICE_ID/preview" \
  -H "x-api-key: $UNCAGED_API_KEY" \
  -o voice-preview.wav

// POST /workspaces/{workspaceId}/live-characters
// Or PATCH /workspaces/{workspaceId}/live-characters/{characterId}
{
  "voiceSource": "custom",
  "voiceReferenceUrl": "https://your-cdn.example/avery-voice.wav",
  "voiceDescription": "A warm, casual American English voice. Relaxed pace and playful delivery."
}

curl --fail-with-body -X PATCH \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-characters/$UNCAGED_CHARACTER_ID" \
  -H "x-api-key: $UNCAGED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "systemPrompt": "You are Avery. Be warm, witty, and concise. Ask one natural follow-up question at a time.",
    "knowledgeText": "Support hours: Monday to Friday, 9am to 5pm Pacific.",
    "openingLines": ["Hey, what brings you here?", "Hi! What are we getting into today?"],
    "cerebro": {
      "personalityTraits": { "extraversion": 75, "playfulness": 80 }
    },
    "maxSessionMinutes": 5
  }'

curl --fail-with-body --max-time 900 -X POST \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-characters/$UNCAGED_CHARACTER_ID/prepare" \
  -H "x-api-key: $UNCAGED_API_KEY"

# Get the latest configuration and preparation status.
curl --fail-with-body \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-characters/$UNCAGED_CHARACTER_ID" \
  -H "x-api-key: $UNCAGED_API_KEY"

{
  "liveCharacter": {
    "id": "your_character_id",
    "status": "active",
    "runtimeStatus": "ready",
    "prepStatus": "ready"
  }
}

curl --fail-with-body -X POST \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-characters/$UNCAGED_CHARACTER_ID/sessions" \
  -H "x-api-key: $UNCAGED_API_KEY" \
  -H "Origin: https://your-app.example" \
  -H "Content-Type: application/json" \
  -d '{
  "launchMode": "webrtc",
  "sessionMode": "conversation",
  "channels": {
    "text": true,
    "voice": false,
    "video": false
  },
  "endUserId": "visitor_123",
  "saveHistory": false,
  "maxSessionSeconds": 300
}'

// conversation.js, browser
export function connectConversation(session, onEvent, onClose = () => {}) {
  return new Promise((resolve, reject) => {
    const socket = new WebSocket(session.conversationStream.url);
    let ready = false;
    const timer = setTimeout(() => {
      reject(new Error('Conversation connection timed out'));
      socket.close();
    }, 15000);
    socket.onopen = () => socket.send(JSON.stringify({
      token: session.conversationStream.token, sampleRate: 48000
    }));
    socket.onmessage = ({ data }) => {
      const event = JSON.parse(data);
      if (event.type === 'ready') {
        ready = true;
        clearTimeout(timer);
        resolve(socket);
      }
      if (event.type === 'error' && !ready) {
        clearTimeout(timer);
        reject(new Error(event.message));
        socket.close();
      }
      onEvent(event);
    };
    socket.onerror = () => {
      if (!ready) { clearTimeout(timer); reject(new Error('WebSocket connection failed')); }
    };
    socket.onclose = () => {
      clearTimeout(timer);
      if (!ready) reject(new Error('Connection closed before ready'));
      onClose();
    };
  });
}

// HTML: <button id="start">Start</button>
// <form id="chat"><input id="message" required><button>Send</button></form>
// <div id="transcript"></div><button id="end">End chat</button>
import { connectConversation } from './conversation.js';

let session, socket, starting = false, ending;
const messages = new Map();
function upsert(message) {
  messages.set(message.id, message);
  const lines = [...messages.values()].map(m => m.role + ': ' + m.text);
  document.querySelector('#transcript').textContent = lines.join('\n');
}
async function endChat() {
  if (ending) return ending;
  const current = session;
  session = undefined;
  socket?.close(); socket = undefined;
  ending = current
    ? fetch('/api/avatar/session/' + current.sessionId + '/end', { method: 'POST' })
    : Promise.resolve();
  try { await ending; } finally { ending = undefined; }
}
document.querySelector('#start').onclick = async () => {
  if (session || starting || ending) return;
  starting = true;
  try {
    const response = await fetch('/api/avatar/session', {
      method: 'POST', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ mode: 'text' })
    });
    if (!response.ok) throw new Error('Could not start session');
    session = await response.json();
    messages.clear();
    socket = await connectConversation(session, event => {
      if (event.type === 'ready') event.messages.forEach(upsert);
      if (event.type === 'transcript') upsert(event); // Replace by id as text streams.
      if (event.type === 'error') console.error(event.message);
    }, () => { void endChat().catch(console.error); });
  } catch (error) { await endChat(); throw error; }
  finally { starting = false; }
};
document.querySelector('#chat').onsubmit = event => {
  event.preventDefault();
  const input = document.querySelector('#message');
  const text = input.value.trim();
  if (!text || socket?.readyState !== WebSocket.OPEN) return;
  socket.send(JSON.stringify({ type: 'text_turn', id: crypto.randomUUID(), text }));
  input.value = '';
};
document.querySelector('#end').onclick = endChat;

curl --fail-with-body -X POST \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-characters/$UNCAGED_CHARACTER_ID/sessions" \
  -H "x-api-key: $UNCAGED_API_KEY" \
  -H "Origin: https://your-app.example" \
  -H "Content-Type: application/json" \
  -d '{
  "launchMode": "webrtc",
  "sessionMode": "conversation",
  "channels": {
    "text": true,
    "voice": true,
    "video": false
  },
  "endUserId": "visitor_123",
  "saveHistory": false,
  "maxSessionSeconds": 300
}'

// public/pcm-capture.js, served from your app's origin
class PcmCapture extends AudioWorkletProcessor {
  process(inputs) {
    const channels = inputs[0];
    if (!channels?.length) return true;
    const count = channels[0].length;
    const pcm = new ArrayBuffer(count * 2);
    const view = new DataView(pcm);
    for (let i = 0; i < count; i++) {
      let mono = 0;
      for (const channel of channels) mono += channel[i] / channels.length;
      mono = Math.max(-1, Math.min(1, mono));
      view.setInt16(i * 2, mono < 0 ? mono * 32768 : mono * 32767, true);
    }
    this.port.postMessage(pcm, [pcm]);
    return true;
  }
}
registerProcessor('pcm-capture', PcmCapture);

// Start from a click. Reuse connectConversation from the Text chat guide.
import { connectConversation } from './conversation.js';

export async function startVoiceChat() {
  const context = new AudioContext({ sampleRate: 48000 });
  await context.resume();
  const activeAudio = new Set();
  let nextAudio = 0, microphoneReady = false, session, socket, mic, capture, closing = false;
  const clearAudio = () => {
    for (const source of activeAudio) source.stop();
    activeAudio.clear(); nextAudio = 0;
  };
  const cleanup = async () => {
    if (closing) return;
    closing = true;
    microphoneReady = false;
    capture?.disconnect();
    mic?.getTracks().forEach(track => track.stop());
    socket?.close(); clearAudio();
    await context.close();
    if (session) await fetch('/api/avatar/session/' + session.sessionId + '/end', { method: 'POST' });
  };
  try {
    // Request permission before allocating a paid session.
    mic = await navigator.mediaDevices.getUserMedia({ audio: {
      channelCount: 1, echoCancellation: true, noiseSuppression: true
    } });
    await context.audioWorklet.addModule('/pcm-capture.js');
    const response = await fetch('/api/avatar/session', {
      method: 'POST', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ mode: 'voice' })
    });
    if (!response.ok) throw new Error('Could not start voice session');
    session = await response.json();
    socket = await connectConversation(session, event => {
      if (event.type === 'microphone_ready') microphoneReady = true;
      if (event.type === 'transcript') console.log(event.role, event.text, event.final);
      if (event.type === 'error') console.error(event.message);
      if (event.type === 'interrupt') clearAudio();
      if (event.type !== 'audio') return;
      const bytes = Uint8Array.from(atob(event.pcm), char => char.charCodeAt(0));
      const view = new DataView(bytes.buffer);
      const buffer = context.createBuffer(1, bytes.length / 2, event.sampleRate);
      const samples = buffer.getChannelData(0);
      for (let i = 0; i < samples.length; i++) samples[i] = view.getInt16(i * 2, true) / 32768;
      const source = context.createBufferSource();
      source.buffer = buffer; source.connect(context.destination);
      const when = Math.max(context.currentTime + 0.02, nextAudio);
      nextAudio = when + buffer.duration;
      activeAudio.add(source);
      source.onended = () => activeAudio.delete(source);
      source.start(when);
    }, () => { void cleanup().catch(console.error); });
    socket.send(JSON.stringify({ type: 'microphone_start', sampleRate: context.sampleRate }));
    const input = context.createMediaStreamSource(mic);
    capture = new AudioWorkletNode(context, 'pcm-capture');
    capture.port.onmessage = ({ data }) => {
      if (microphoneReady && socket.readyState === WebSocket.OPEN) {
        if (socket.bufferedAmount > 192000) { socket.close(); return; }
        socket.send(data); // Mono little-endian PCM16 binary, not encoded WebM.
      }
    };
    const silent = context.createGain(); silent.gain.value = 0;
    input.connect(capture).connect(silent).connect(context.destination);
    return cleanup; // Call on your End button, including on errors.
  } catch (error) { await cleanup(); throw error; }
}

curl --fail-with-body -X POST \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-characters/$UNCAGED_CHARACTER_ID/sessions" \
  -H "x-api-key: $UNCAGED_API_KEY" \
  -H "Origin: https://your-app.example" \
  -H "Content-Type: application/json" \
  -d '{
  "launchMode": "webrtc",
  "sessionMode": "conversation",
  "channels": {
    "text": true,
    "voice": true,
    "video": true
  },
  "endUserId": "visitor_123",
  "saveHistory": false,
  "maxSessionSeconds": 300
}'

// HTML: <button id="start">Start</button><div id="avatar"></div>
// <button id="end">End call</button>
import { Room, RoomEvent, Track } from 'https://sequencer.media/realtime/client-v1.js';

let room, session, starting = false, ending = false;
const container = document.querySelector('#avatar');
async function endCall() {
  if (ending) return;
  ending = true;
  try {
    await room?.disconnect(); // Also unpublishes the microphone.
    container.replaceChildren();
    if (session) await fetch('/api/avatar/session/' + session.sessionId + '/end', { method: 'POST' });
    room = session = undefined;
  } finally { ending = false; }
}
document.querySelector('#start').onclick = async () => {
  if (session || starting || ending) return;
  starting = true;
  room = new Room();
  room.on(RoomEvent.TrackSubscribed, track => {
    if (track.kind !== Track.Kind.Video && track.kind !== Track.Kind.Audio) return;
    const element = track.attach();
    if (track.kind === Track.Kind.Video) {
      element.playsInline = true; element.style.width = '100%';
    }
    container.appendChild(element);
  });
  room.on(RoomEvent.TrackUnsubscribed, track => {
    track.detach().forEach(element => element.remove());
  });
  room.on(RoomEvent.Disconnected, () => { void endCall().catch(console.error); });
  try {
    const response = await fetch('/api/avatar/session', {
      method: 'POST', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ mode: 'video' })
    });
    if (!response.ok) throw new Error('Could not start video session');
    session = await response.json();
    await room.connect(session.livekitUrl, session.livekitClientToken);
    await room.startAudio();
    await room.localParticipant.setMicrophoneEnabled(true);
  } catch (error) { await endCall(); throw error; }
  finally { starting = false; }
};
document.querySelector('#end').onclick = endCall;
// Provide an Enable audio button that calls room.startAudio() if autoplay is blocked.
// For typed input, use your backend's messages route from Send a text turn.

// Start the session on your backend, with the normal session endpoint.
{
  "launchMode": "webrtc",
  "sessionMode": "audio_stream",
  "channels": { "text": false, "voice": true, "video": true },
  "endUserId": "visitor_123",
  "maxSessionSeconds": 300
}

// Browser: connect to LiveKit using the Connect with LiveKit guide.
// Feed your own agent's speech into a Web Audio destination.
const context = new AudioContext();
await context.resume();
const output = context.createMediaStreamDestination();
// Connect your speech-producing AudioNode to output.
// Do not also connect that speech to speakers, or it will play twice.
const speechTrack = output.stream.getAudioTracks()[0];
await room.localParticipant.publishTrack(speechTrack, {
  source: Track.Source.Microphone, dtx: false
});
// Keep this track alive through pauses. Let returned audio finish before ending.
// On End: disconnect the room, close the AudioContext, and call End Session.

// Default: your backend owns and supplies history for the authenticated user.
{
  "saveHistory": false,
  "endUserId": "visitor_123",
  "conversationHistory": [
    { "role": "user", "content": "My dog is named Luna." },
    { "role": "assistant", "content": "How is Luna doing?" }
  ]
}
// Add the usual channels and session fields. Save final transcript events in
// your backend and supply the relevant recent messages when starting again.
// Maximum: 60 messages, 16000 characters per message, 64 KiB total UTF-8 content.

// New API conversations use client-managed history. Your backend chooses
// its retention policy. Hosted history creation is reserved for Sequencer's
// own products. Existing legacy hosted conversation IDs can still resume.

// On your backend: load your own saved user/assistant messages.
// These stores and your app authentication are integration points you provide.
import { historyStore } from './your-app-auth.js';
import { startAvatar } from './avatar-api.js';

const history = await historyStore.recent({
  userId: user.id, workspaceId: process.env.UNCAGED_WORKSPACE_ID,
  characterId: process.env.UNCAGED_CHARACTER_ID, limit: 60, maxBytes: 65536
});
const session = await startAvatar(
  user.id, { text: true, voice: true, video: false }, history
);
// Each call returns a new session and fresh credentials.
// Save completed transcript events in your own history store after checking
// session ownership. Preserve your app's conversation ID across calls.

curl --fail-with-body -X POST \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-character-sessions/{sessionId}/messages" \
  -H "x-api-key: $UNCAGED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Hey Avery, what should we try first?" }'

curl --fail-with-body -X POST \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-character-sessions/{sessionId}/end" \
  -H "x-api-key: $UNCAGED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "USER_CLOSED" }'

# For an abandoned start that has not returned a sessionId:
curl --fail-with-body -X POST \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-character-session-starts/{startToken}/cancel" \
  -H "x-api-key: $UNCAGED_API_KEY"

# Upload a source clip and describe when to use it.
curl --fail-with-body -X POST \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-characters/$UNCAGED_CHARACTER_ID/custom-animations/upload" \
  -H "x-api-key: $UNCAGED_API_KEY" \
  -F "file=@wave.mp4" -F "name=Wave" -F "trigger=Wave when greeting a visitor"

# Prepare the returned customAnimation.id.
curl --fail-with-body -X POST \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-characters/$UNCAGED_CHARACTER_ID/custom-animations/{animationId}/prepare" \
  -H "x-api-key: $UNCAGED_API_KEY"

# Once its status is ready, trigger it in an active video conversation.
curl --fail-with-body -X POST \
  "$UNCAGED_API_BASE/workspaces/$UNCAGED_WORKSPACE_ID/live-character-sessions/{sessionId}/animations/trigger" \
  -H "x-api-key: $UNCAGED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "animationId": "your_animation_id" }'

const maxCost = session.billing.reservedUsd;
const estimatedCost = session.billing.usdPerMinute * (connectedSeconds / 60);
// Final settlement comes from the API. This is an estimate.