Boson Higgs Realtime

Real-time speech-to-speech service powered by Boson AI’s Higgs Realtime API

Overview

BosonRealtimeLLMService connects a Pipecat pipeline to Boson AI’s Higgs Realtime API. It accepts live audio or text and streams audio or text responses without requiring separate STT, LLM, and TTS services.

The community integration supports voice activity detection, interruption handling, user transcriptions, function calling, and text-only responses.

Installation

Install the community-maintained package from PyPI:

uv add pipecat-boson

Configuration

Set your Boson API key and the Higgs Realtime endpoint in the server environment:

export BOSON_API_KEY=bai-xxxx
export BOSON_REALTIME_URL=wss://api.boson.ai/v1/realtime/
export BOSON_REALTIME_MODEL=higgs-realtime

Create the service and add it to your Pipecat pipeline in place of separate STT, LLM, and TTS services:

import os

from pipecat_boson.realtime import BosonRealtimeLLMService


llm = BosonRealtimeLLMService(
    url=os.environ["BOSON_REALTIME_URL"],
    api_key=os.environ["BOSON_API_KEY"],
    model=os.getenv("BOSON_REALTIME_MODEL", "higgs-realtime"),
    voice="default",
    instructions="You are a concise and helpful voice assistant.",
)

Common parameters

url · str · required

Higgs Realtime WebSocket endpoint.

api_key · str · required

Boson API key. It is required when using the hosted API.

model · str · default: "higgs-realtime"

Higgs Realtime model ID.

voice · str · default: "default"

Voice preset or voice ID used for audio responses.

instructions · str

System instructions used to initialize the realtime session.

output_modalities · List[Literal['audio', 'text']] · default: "['audio']"

Response modality. Choose exactly one of audio or text.

turn_detection · Dict · default: "server_vad"

OpenAI-compatible server or semantic VAD configuration.

input_audio_transcription · Dict

Optional input transcription configuration. A non-empty model enables user transcript frames.

tools · Any

Python functions or Pipecat-compatible tool definitions available to the model.

See the integration README for the complete constructor and session configuration reference.

Minimal pipeline

The following example assumes transport is an existing Pipecat audio transport:

from pipecat.pipeline.pipeline import Pipeline
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import (
    LLMContextAggregatorPair,
)


context = LLMContext()
user_aggregator, assistant_aggregator = LLMContextAggregatorPair(
    context,
    realtime_service_mode=True,
)

pipeline = Pipeline(
    [
        transport.input(),
        user_aggregator,
        llm,
        transport.output(),
        assistant_aggregator,
    ]
)

Compatibility

The current package supports pipecat-ai>=1.4.0,<2 and is tested with Pipecat v1.6.0. Refer to the integration repository for the latest compatibility information.

Resources

Integration guide

Setup instructions, complete examples, configuration options, and troubleshooting

PyPI package

Package releases and installation metadata

Boson documentation

Higgs Realtime API documentation

Boson API keys

Create and configure a Boson API key