Custom voices

The Voices API lets you create custom voices for your Characters. Design an entirely new voice from a text prompt, or clone a voice from an audio sample. Once created, assign the voice to any Avatar.

Voice design

Create a voice by describing the characteristics you want. The prompt should include details like tone, accent, pacing, and personality.

Node

import RunwayML from '@runwayml/sdk';

const client = new RunwayML();

const voice = await client.voices.create({
  name: 'Brand Ambassador',
  from: {
    type: 'text',
    prompt: 'A warm, friendly voice with a slight British accent. Speaks at a measured pace with a professional yet approachable tone.',
    model: 'eleven_ttv_v3',
  },
});

console.log('Voice created:', voice.id);

Python

from runwayml import RunwayML

client = RunwayML()

voice = client.voices.create(
  name='Brand Ambassador',
  from_={
    'type': 'text',
    'prompt': 'A warm, friendly voice with a slight British accent. Speaks at a measured pace with a professional yet approachable tone.',
    'model': 'eleven_ttv_v3',
  },
)

print('Voice created:', voice.id)

Parameter	Type	Description
name	string	A name for the voice (max 100 characters).
from.type	"text"	Indicates voice design from a text prompt.
from.prompt	string	A description of the desired voice characteristics. Must be at least 20 characters.
from.model	string	The voice design model. Use eleven_ttv_v3 (latest) or eleven_multilingual_ttv_v2.

Voice cloning

Clone a voice from an audio sample. Provide a clear recording with minimal background noise and varied tone for best results.

Node

const voice = await client.voices.create({
  name: 'Cloned Narrator',
  from: {
    type: 'audio',
    audio: 'https://example.com/voice-sample.mp3',
  },
});

console.log('Voice created:', voice.id);

Python

voice = client.voices.create(
  name='Cloned Narrator',
  from_={
    'type': 'audio',
    'audio': 'https://example.com/voice-sample.mp3',
  },
)

print('Voice created:', voice.id)

The audio sample must be between 10 seconds and 5 minutes long, and at most 10 MB. You can pass a public HTTPS URL, a runway:// upload URI, or a data:audio/... data URI.

Voice status

Voice creation is asynchronous. After calling create, poll the voice until its status is READY.

Node

const voice = await client.voices.retrieve(voiceId);

if (voice.status === 'READY') {
  console.log('Preview:', voice.previewUrl);
}

Python

voice = client.voices.retrieve(id=voice_id)

if voice.status == 'READY':
    print('Preview:', voice.preview_url)

Status	Description
PROCESSING	Voice is being generated. Poll until ready.
READY	Voice is ready. A previewUrl is available.
FAILED	Generation failed. Check failureReason.

Assigning a custom voice to an Avatar

Once the voice is ready, assign it to an Avatar by setting the voice type to custom and providing the voice ID.

Node

await client.avatars.update(avatarId, {
  voice: {
    type: 'custom',
    id: voice.id,
  },
});

Python

client.avatars.update(
  avatar_id,
  voice={
    'type': 'custom',
    'id': voice.id,
  },
)

You can also create a new Avatar with a custom voice directly:

Node

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

Python

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

Listing voices

Retrieve all custom voices for your organization.

Node

const voices = await client.voices.list();

for await (const voice of voices) {
  console.log(voice.name, voice.status);
}

Python

for voice in client.voices.list():
    print(voice.name, voice.status)

You can also manage custom voices through the Developer Portal. See the API reference for all available endpoints.