Introduction

What is Protoface?

Protoface is a developer-facing realtime avatar API. You call POST /v1/sessions, stream audio in, and a talking-head avatar speaks that audio back as video over LiveKit (WebRTC).

Think “Tavus / Simli / HeyGen-style avatars, as an API.” You stay in control of your media transport — Protoface schedules each session onto a GPU worker that runs the avatar model and publishes video into a LiveKit room you own.

Quickstart Go from signup to a running LiveKit session in under 10 minutes.

API Reference Every endpoint, generated from the OpenAPI spec.

Architecture How the control plane, workers, and transport fit together.

Error reference The error envelope and every stable error.code.

How it works

1. Create a session

   Send POST /v1/sessions with an avatar_id and a transport config. The API responds in under 300 ms — the session is queued, not yet running.

2. A worker picks it up

   The control plane schedules your session onto an available GPU worker, which joins your LiveKit room and starts publishing a video track.

3. Stream audio in, get video out

   You push audio into the room; the avatar speaks it back as a video track in realtime. First frame typically lands within a few seconds.

4. Observe and end

   Poll GET /v1/sessions/{id} for status and timing, read aggregate consumption from GET /v1/usage, and call POST /v1/sessions/{id}/end when you’re done.

Core concepts

• Session — a single realtime avatar run. The headline resource. See Sessions.
• Avatar — the face the session renders. v0 ships platform demo avatars (e.g. av_demo). See Avatars.
• Transport — how media flows. Today that’s LiveKit BYO (you own the room). See Transports.
• Usage — aggregated, read-only consumption per org. See Usage.

Bring your own LiveKit

Protoface is BYO transport: you own the LiveKit room and mint the worker token with your own LiveKit API key and secret. We never see or store your LiveKit credentials — the worker joins with a token you minted and scoped. This matches the universal convention across LiveKit Agents avatar plugins. See Transports for the full contract.

Note

Protoface is on a single, forward-compatible /v1 API. Once a field, endpoint, header, error code, enum value, or event type ships, it is part of the contract and we don’t rename or remove it — only add alongside. See the changelog for the (additive-only) history.

v0 status

Protoface is at v0: the full platform runs against a deterministic mock avatar runtime while the production face model is finalized. The API, session lifecycle, transports, limits, and SDKs are all stable and final — the pixels are placeholder. See Known limitations for the exact caveats.