Skip to main content
Community-maintained integration. This service is built and maintained by Akapulu Labs. Pipecat does not test or officially support it. Please report issues and request changes on the source repository. Learn more about community integrations.

Overview

AkapuluAvatar is a Pipecat processor that sits after your speech model. It sends assistant audio to the Akapulu Labs worker. The worker joins the Daily room for that call and publishes the avatar video and audio. Your voice bot itself does not publish camera or microphone. On InterruptionFrame, the processor tells the worker to cut the in-flight reply so the avatar can stop speaking when the caller barges in.

Source Repository

Source code, examples, and issues for the Akapulu Labs integration

PyPI Package

The pipecat-akapulu package on PyPI

Akapulu Labs Docs

Create the Daily room, start a live session, and wire AkapuluAvatar

Akapulu Labs

Create an account and get an API key

Installation

This is a community-maintained package distributed separately from pipecat-ai:
You’ll also need Pipecat with Daily and the STT, TTS, and LLM extras you use.

Prerequisites

Akapulu Labs account setup

Before using the Akapulu Labs video avatar, you need:
  1. Akapulu Labs API key: Create an account at Akapulu Labs
  2. Avatar ID: UUID of a public or private avatar. See our catalog for public avatars. Private avatars are available on our enterprise plan.
  3. Daily API key: Daily is used to create the room when you call create_akapulu_call
You’ll also need API keys for the STT, TTS, and LLM services used in your pipeline.

Required environment variables

  • AKAPULU_API_KEY: Your Akapulu Labs API key
  • DAILY_API_KEY: Your Daily API key (create_akapulu_call reads this)

Configuration

create_akapulu_call

Run this on your server before the voice bot starts. It creates a private Daily room for three participants and mints the browser, voice-bot, and avatar worker tokens. It uses your AKAPULU_API_KEY to POST /api/live-sessions/ to Akapulu Labs. It returns room_url, bot_token, browser_token, and session_id. The worker token is sent to Akapulu Labs and is not returned.
str
required
UUID of a public or private avatar. See our catalog for public avatars. Private avatars are available on our enterprise plan.
bool
required
Whether a visible “This is AI” label is shown on the live avatar video feed.
aiohttp.ClientSession
required
HTTP client for creating the Daily room and for the Akapulu Labs live-session request.
float
default:"7200"
Daily room lifetime in seconds. Defaults to two hours. Daily removes everyone when the room expires.
create_akapulu_call spawns an avatar worker. That worker can take 5 to 10 seconds to start up.While that worker starts up, AkapuluAvatar pushes RTVI server messages:
  • type: status
  • call_is_ready: true when the first video frame is published
  • completion_percent
  • latest_update_text
Keep a loading state up until call_is_ready is true.
If you would like to create the Daily room yourself, skip create_akapulu_call. We recommend these room settings:
  • privacy: private
  • max_participants: 3 (the end user joins as You, your voice bot joins as the name you pass to DailyTransport, Assistant in the example below, and the avatar worker joins as Avatar)
  • enable_chat: off
  • enable_prejoin_ui: off
  • eject_at_room_exp: on, so Daily removes everyone when exp is reached
Then mint the avatar worker token and POST /api/live-sessions/ to Akapulu Labs with avatar_id, show_ai_label, room_url, and avatar_token. The response is session_id.
The avatar worker joins the room as Avatar and publishes audio and video. Its token needs permission to send audio and video.Daily shows the end user and the avatar. The voice bot is in the room and does not get its own tile.create_akapulu_call already does this.

AkapuluAvatar

Constructor parameters for AkapuluAvatar:
str
required
Live session id returned by create_akapulu_call or POST /api/live-sessions/.
float
default:"0"
Seconds to wait after TTSStoppedFrame before the audio counts as stopped, so the avatar can transition from speaking back to idle. We recommend 0. Custom engineered pipelines with voice bots that trickle in audio more slowly might need different values. See our enterprise plan.
See the source repository for the authoritative, up-to-date list of parameters, loading-status RTVI messages, and the complete example.

Usage

When you construct your voice bot and create your transport processor, leave audio out and video out off. Your voice bot will not publish audio or video into the Daily room. The Akapulu Labs avatar worker publishes the audio and video. Add AkapuluAvatar after your TTS processor so it forwards that audio to the avatar worker.
The browser joins with browser_token as You and stays subscribed to the Avatar microphone. That track is the voice the person on the call hears. Pipecat subscribes the voice bot to every remote microphone. When Avatar joins, turn that microphone off so the voice bot only hears the caller. Call this once. Do not set subscriptions again on a participant update.
The avatar worker needs about 800 ms of assistant audio before it starts rendering the video. The render itself, given the audio, only takes around 150ms.You might see added latency in your bot’s response even if your TTS provider’s TTFA is low, due to this buffer accumulation.A TTS that trickles audio in slowly fills that buffer late, so the response is slower and the avatar gestures less.We recommend a TTS that sends audio in waves.Cartesia has been the best in our testing.
See the foundational example and akapulu-examples for a complete Daily pipeline.

Compatibility

Tested with Pipecat v1.14.0, v1.15.0, and v1.16.0 (Python 3.11+). Requires Pipecat 1.12.0 or newer. Check the source repository for the latest tested version and changelog.