> ## Documentation Index
> Fetch the complete documentation index at: https://daily-docs-deploy-no-op-warm-pods-t3002.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Boson Higgs Realtime

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

export const CommunityMaintained = ({maintainer, maintainerUrl, repo}) => <Note>
    <strong>Community-maintained integration.</strong> This service is built and
    maintained by{" "}
    <a href={maintainerUrl} target="_blank" rel="noreferrer">
      {maintainer}
    </a>
    . Pipecat does not test or officially support it. Please report issues and
    request changes on the{" "}
    <a href={repo} target="_blank" rel="noreferrer">
      source repository
    </a>
    . Learn more about{" "}
    <a href="/api-reference/server/services/community-integrations">
      community integrations
    </a>
    .
  </Note>;

<CommunityMaintained maintainer="Boson AI" maintainerUrl="https://github.com/boson-ai" repo="https://github.com/boson-ai/pipecat-boson" />

## 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:

```bash theme={null}
uv add pipecat-boson
```

## Configuration

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

```bash theme={null}
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:

```python theme={null}
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

<ParamField path="url" type="str" required>
  Higgs Realtime WebSocket endpoint.
</ParamField>

<ParamField path="api_key" type="str" required>
  Boson API key. It is required when using the hosted API.
</ParamField>

<ParamField path="model" type="str" default="higgs-realtime">
  Higgs Realtime model ID.
</ParamField>

<ParamField path="voice" type="str" default="default">
  Voice preset or voice ID used for audio responses.
</ParamField>

<ParamField path="instructions" type="str">
  System instructions used to initialize the realtime session.
</ParamField>

<ParamField path="output_modalities" type="List[Literal['audio', 'text']]" default="['audio']">
  Response modality. Choose exactly one of audio or text.
</ParamField>

<ParamField path="turn_detection" type="Dict" default="server_vad">
  OpenAI-compatible server or semantic VAD configuration.
</ParamField>

<ParamField path="input_audio_transcription" type="Dict">
  Optional input transcription configuration. A non-empty model enables user
  transcript frames.
</ParamField>

<ParamField path="tools" type="Any">
  Python functions or Pipecat-compatible tool definitions available to the
  model.
</ParamField>

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:

```python theme={null}
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

<CardGroup cols={2}>
  <Card title="Integration guide" icon="github" href="https://github.com/boson-ai/pipecat-boson#readme">
    Setup instructions, complete examples, configuration options, and
    troubleshooting
  </Card>

  <Card title="PyPI package" icon="cube" href="https://pypi.org/project/pipecat-boson/">
    Package releases and installation metadata
  </Card>

  <Card title="Boson documentation" icon="book" href="https://docs.boson.ai/">
    Higgs Realtime API documentation
  </Card>

  <Card title="Boson API keys" icon="key" href="https://docs.boson.ai/authentication">
    Create and configure a Boson API key
  </Card>
</CardGroup>