Voices

Every avatar can speak in whatever voice you register for your account. Cloning a new voice takes one API call and a short reference clip; there’s no separate training step to wait on.

Recording a good reference clip

Tip

8-10 seconds of clean, single-speaker audio is enough. Avoid background music or noise, avoid clipping/distortion, and avoid long silences at the start or end of the file.

Option A: upload a file, then reference it

1. Upload the clip with POST /v1/files:

   curl -X POST https://api.2wai.ai/v1/files \
     -H "Authorization: Bearer $TWAI_SECRET_KEY" \
     -F "file=@reference-clip.wav"

   Response

   { "file_id": "file_7c2e9a1b4f6d" }

2. Create the voice from that file_id:

   curl -X POST https://api.2wai.ai/v1/voices \
     -H "Authorization: Bearer $TWAI_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "narrator",
       "file_id": "file_7c2e9a1b4f6d"
     }'

   Response

   { "voice_id": "voice_2b7e1a9c", "status": "ready" }

Option B: clone directly from a URL

If your reference clip is already hosted somewhere publicly reachable, skip the upload step entirely:

curl -X POST https://api.2wai.ai/v1/voices \
  -H "Authorization: Bearer $TWAI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "narrator",
    "url": "https://example.com/reference-clip.wav"
  }'

Provide exactly one of file_id or url, not both.

Using a voice

Pass the resulting voice_id when you create a session:

curl -X POST https://api.2wai.ai/v1/sessions \
  -H "Authorization: Bearer $TWAI_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar_id": "avt_9f2c1a4b7e3d",
    "mode": "video",
    "voice_id": "voice_2b7e1a9c"
  }'

If you omit voice_id, the session uses the avatar’s default voice.

Listing your voices

cURL

curl https://api.2wai.ai/v1/voices \
  -H "Authorization: Bearer $TWAI_SECRET_KEY"

Node.js

const res = await fetch('https://api.2wai.ai/v1/voices', {
  headers: { Authorization: `Bearer ${process.env.TWAI_SECRET_KEY}` },
});
const voices = await res.json();

Next

• Sessions for how voice_id fits into session creation.
• Bring your own TTS if you’d rather not use 2wai’s speech synthesis at all.