An avatar (ava_…) is a reusable source you can drive with turns or lipsync. Create one from a portrait image or a source video.

​
From a portrait image

import { RealtimeAvatarClient } from "realtime-avatar";

const client = RealtimeAvatarClient.platform({
  apiKey: process.env.REALTIME_AVATAR_API_KEY!,
});

const { avatar } = await client.createImageAvatar({
  displayName: "Mira",
  image: portraitBlob,        // or use createRemoteAsset with a URL
  defaultVoiceId: "voice_…",
});
console.log(avatar.id);       // ava_…

​
From a source video (URL)

Source-video avatars lipsync against real footage. Ingest by URL — don’t push large MP4 multipart bodies through the API. 
const { avatar, videoCache } = await client.createVideoAvatarFromUrl({
  displayName: "Kael",
  videoUrl: "https://example.com/idle.mp4",
  defaultVoiceId: "voice_…",
  videoCache: { keyframe_stride: 5 },
});

if (videoCache?.status === "ready") {
  await client.prepare({ avatar_id: avatar.id, source_kind: "source_video" });
}

​
Quick, no-avatar lipsync

For one-off renders you can skip avatar creation and pass a portraitUrl directly to lipsync — it registers the portrait on the fly.

​
List and manage

const { data } = await client.listAvatars();
await client.updateAvatar("ava_…", { displayName: "New name" });
await client.deleteAvatar("ava_…");
Avatar ids always start with ava_. Voices come from the Cartesia voice list, or let the platform match one automatically when you create the avatar.