Concepts

Four ideas cover almost everything in this API.

Avatar

The character being rendered, a 3D or video-based likeness identified by an avatar_id (e.g. avt_9f2c1a4b7e3d).

Voice

The speech synthesis identity used when 2wai generates audio for you, identified by a voice_id.

Session

A live, running instance of an avatar: the thing your server creates, drives, and eventually ends.

Mode

What kind of stream a session produces. Today, that’s video.

Avatars

An avatar is the visual identity a session renders. avatar_id values look like avt_9f2c1a4b7e3d. Avatars are provisioned for your account today; self-serve avatar creation is on the roadmap. If you need a new avatar, talk to your 2wai account contact.

An avatar and a voice are independent: the same avatar can speak with different voices across different sessions, and the same voice can be reused across avatars.

Voices

A voice is a synthesis identity 2wai uses to generate speech from text when you call /speak. You can:

• Use a voice that was set up for your account, or
• Register your own with POST /v1/voices, cloned instantly from a short reference clip (see Voices)

If you’d rather not use 2wai’s TTS at all, you can skip voices entirely and push your own synthesized audio with POST /v1/sessions/{id}/audio, see Bring your own TTS. In that case voice_id is irrelevant to that session.

Sessions

A session is one running instance of an avatar: the unit you create, drive, and end. Creating a session (POST /v1/sessions) starts the render pipeline and returns:

• session_id: how your server refers to it on every subsequent call
• client_token and websocket_url: what you hand to the browser so it can receive the stream

A session stays alive until you end it (DELETE /v1/sessions/{id}), it’s idle long enough to time out, or your connection is interrupted for too long. See Sessions for the full lifecycle, including pausing a session’s rendering without ending it and reconnecting after a dropped connection.

Each session counts against your account’s concurrency limit, see Limits & concurrency.

Modes

mode on POST /v1/sessions selects what kind of stream the session produces. Currently "video" is the only supported mode: a lip-synced video-and-audio stream delivered over WebSocket via MSE, as covered throughout this site. Additional modes may be added in the future; check the API Reference for the current list.

How they combine

A typical request:

{
  "avatar_id": "avt_9f2c1a4b7e3d",
  "mode": "video",
  "voice_id": "voice_2b7e1a9c"
}

…starts a video session of a specific avatar, speaking in a specific voice. Everything else in this API is about creating that session, driving what it says, and eventually ending it.

Next: Sessions for the lifecycle in depth, or Streaming into your app for the browser side.