Skip to content
2wai Developer API

Introduction

The 2wai Avatar API lets you add a live, talking, lip-synced avatar to any product you’re building: a support widget, a companion app, a training simulator, a kiosk, without running any video, audio, or rendering infrastructure yourself.

You control what the avatar says. 2wai handles turning that into a real-time video stream: text-to-speech, lipsync rendering, and delivery to the browser over a WebSocket. If you’d rather use your own TTS or your own LLM, the API is built to let you swap either one in.

How it fits together

Section titled “How it fits together”

2wai uses a split-plane design: your server holds credentials and makes decisions, and the browser only renders what it’s told to.

sequenceDiagram
  participant Server as Your Server
  participant API as 2wai API
  participant Browser as Browser

  Server->>API: POST /v1/sessions (Bearer sk_...)
  API-->>Server: session_id, client_token, websocket_url
  Server-->>Browser: client_token, websocket_url
  Browser->>API: WebSocket connect (websocket_url)
  API-->>Browser: fMP4 video/audio stream
  Server->>API: POST /v1/sessions/{id}/speak (text)
  API-->>Browser: lip-synced speech, streamed live
  • Your server holds a secret key (sk_...) and never shares it with the browser. It creates sessions and tells the avatar what to say.
  • Your browser holds only a short-lived client_token, scoped to a single session, and uses it purely to receive video; it never calls the REST API directly.
  • 2wai runs the avatar rendering pipeline (text-to-speech or your own audio, lipsync, and video encoding) and streams the result down the WebSocket.

This split means a leaked browser session can’t be used to mint new sessions, run up your bill, or exfiltrate your secret key. The worst it can do is watch (or disconnect from) the one video stream it was already scoped to. See Authentication for the full model.

What you can build

Section titled “What you can build”

Live video avatar

Stream a real-time, lip-synced avatar into a <video> element with a couple hundred milliseconds of setup code. See the Quickstart.

Bring your own brain

Use any LLM you like to write what the avatar says: OpenAI, Anthropic, your own fine-tune, or a rules engine. See Bring your own brain.

Bring your own TTS

Already have a text-to-speech pipeline you like? Push its audio directly and skip ours. See Bring your own TTS.

Custom voices

Clone a voice from a short reference clip in one API call. See Voices.

Base URL

Section titled “Base URL”

All REST endpoints are served from:

https://api.2wai.ai

Next steps

Section titled “Next steps”
Quickstart Get a live avatar on screen in about five minutes.
Authentication Secret keys, client tokens, and how they work together.
Concepts Avatars, voices, sessions, and modes.
API Reference Every customer-facing endpoint, generated from the OpenAPI schema.