Core Concepts

Avatars and Sessions

Understanding the distinction between Avatars and Sessions is fundamental to building with the Characters API.

Avatars are persistent personas with a defined appearance, voice, and personality. Define your Avatar with a single reference image—any visual style works, from photorealistic humans to animated mascots to stylized brand characters. Configure voice, personality, knowledge base, and conversational actions.

Sessions are live WebRTC connections for real-time conversation. Each Session connects a user to an Avatar for a single interaction. Sessions have a maximum duration of 5 minutes.

Session lifecycle

Sessions progress through a defined set of states:

                    ┌───────────┐
         ┌──────────┤ NOT_READY ├──────────┐
         │          └─────┬─────┘          │
         │                │                │
         ▼                ▼                ▼
     CANCELLED          READY           FAILED
                       ┌──┴──┐
                       │     │
                       ▼     ▼
                    RUNNING FAILED
                    ┌──┴──┐
                    │     │
                    ▼     ▼
                COMPLETED CANCELLED

Status	Description
NOT_READY	Session is being provisioned. Poll until ready.
READY	Session is ready to connect. The sessionKey is available.
RUNNING	WebRTC connection is active. The conversation is in progress.
COMPLETED	Session ended normally after the conversation finished.
FAILED	Session encountered an error. Check the failure field for details.
CANCELLED	Session was explicitly cancelled before completion.

One-time consume

Session credentials can only be retrieved once. If the WebRTC connection fails after credentials are consumed, you must create a new Session.

Creating character

Developer Portal

The Developer Portal provides a visual interface for managing Characters:

1. Go to the Characters tab
2. Click Create a Character
3. Define your Character with a single reference image
4. Configure voice, personality, knowledge base, and conversational actions
5. Preview and test before deploying

The portal also lets you preview available voices and access session recordings.

Portal = API

Everything you see in the Developer Portal can be done via the API. The portal is built on the same public API available to you.

API

Create and manage Avatars programmatically for automated workflows or dynamic Avatar generation:

Node

import RunwayML from '@runwayml/sdk';

const client = new RunwayML();

const avatar = await client.avatars.create({
  name: 'Support Agent',
  referenceImage: 'https://example.com/avatar.png',
  voice: {
    type: 'runway-live-preset',
    presetId: 'clara',
  },
  personality: 'You are a helpful customer support agent...',
});

Python

from runwayml import RunwayML

client = RunwayML()

avatar = client.avatars.create(
  name='Support Agent',
  reference_image='https://example.com/avatar.png',
  voice={
    'type': 'runway-live-preset',
    'preset_id': 'clara',
  },
  personality='You are a helpful customer support agent...',
)

See the API reference for the complete list of Avatar management endpoints.

Reference image guidelines

Generate expressive Avatars from a single image with zero fine-tuning required. For best results:

• Any visual style works: photorealistic humans, animated mascots, stylized brand characters
• Use high-quality images with good lighting
• Ensure the face is clearly visible and centered
• Avoid images with multiple people or obstructions
• Recommended aspect ratio: 1088×704

Voice configuration

Configure your Avatar’s voice using voice presets. Avatars support full conversational expressiveness including natural speech patterns and lip-syncing. Here are some examples:

Preset ID	Name	Style
clara	Clara	Soft, approachable
victoria	Victoria	Firm, professional
vincent	Vincent	Knowledgeable, authoritative

Node

voice: {
  type: 'runway-live-preset',
  presetId: 'clara',
}

Python

voice={
  'type': 'runway-live-preset',
  'preset_id': 'clara',
}

Preview all available voices in the Developer Portal.