> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boson.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Hear your first spoken Higgs Realtime reply in a few minutes with Python.

This quickstart connects over WebSocket, sends a text message, and plays the model's spoken reply through your speakers. One session does everything — the model listens and speaks natively, with no separate transcription or synthesis steps to manage.

<Tip>
  **Looking for an easier path?** [LiveKit](/models/higgs-realtime/integrations/livekit) and [Pipecat](/models/higgs-realtime/integrations/pipecat) have Higgs Realtime support built in and handle the WebSocket, audio, and interruption plumbing for you — often the fastest route to a production voice agent. Already running on OpenAI's Realtime API? [Migrate your existing integration](/models/higgs-realtime/migrate-an-existing-integration) with a few config changes. This page covers the raw WebSocket path — the best way to learn how the API actually works.
</Tip>

## How it works

Your app holds a single WebSocket session and exchanges JSON events with the model:

```mermaid theme={null}
sequenceDiagram
    participant App as Your app
    participant RT as wss://api.boson.ai/v1/realtime
    App->>RT: session.update — voice, turn detection, instructions
    App->>RT: conversation.item.create — a user message
    App->>RT: response.create
    RT-->>App: response.output_audio.delta (audio chunks)
    RT-->>App: response.output_audio_transcript.delta (text)
    RT-->>App: response.done
```

That's the whole loop. When you stream microphone audio instead of text, turn detection makes the last step automatic — the model replies on its own when you stop speaking, no `response.create` needed.

## Before you begin

You need:

* A [Boson API key](/authentication) stored in `BOSON_API_KEY`
* Available credit — new accounts must claim their [free trial credit](/free-trial-credit) before their first API call
* Python 3.10 or later with the `websockets` and `sounddevice` packages
* Speakers or headphones — the reply plays as audio

```bash theme={null}
export BOSON_API_KEY="bai-xxxx"
pip install websockets sounddevice
```

New to Boson AI? [Set up your account](/set-up-your-account) walks through all of it.

## Connect and play a reply

Connect, configure the session, send a text message, and play the model's spoken reply:

```python theme={null}
import asyncio
import base64
import json
import os
import sounddevice as sd
import websockets

async def voice_agent():
    # Speaker output matching the default audio format: 24 kHz, 16-bit, mono PCM
    speaker = sd.RawOutputStream(samplerate=24000, channels=1, dtype="int16")
    speaker.start()

    async with websockets.connect(
        "wss://api.boson.ai/v1/realtime",
        additional_headers={"Authorization": f"Bearer {os.environ['BOSON_API_KEY']}"}
    ) as ws:
        # Configure session
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "model": "higgs-realtime",
                "instructions": "You are a helpful assistant.",
                "audio": {
                    "input": {"turn_detection": {"type": "server_vad"}},
                    "output": {"voice": "default"}
                }
            }
        }))

        # Send a text message
        await ws.send(json.dumps({
            "type": "conversation.item.create",
            "item": {"type": "message", "role": "user",
                     "content": [{"type": "input_text", "text": "Hello!"}]}
        }))
        await ws.send(json.dumps({"type": "response.create"}))

        # Play audio responses as they stream in
        async for msg in ws:
            event = json.loads(msg)
            if event["type"] == "response.output_audio.delta":
                speaker.write(base64.b64decode(event["delta"]))
            elif event["type"] == "response.output_audio_transcript.done":
                print("Assistant:", event["transcript"])
            elif event["type"] == "response.done":
                break

    speaker.stop()

asyncio.run(voice_agent())
```

You should hear the assistant speak its reply out loud, then see its transcript printed.

The reply arrives as a stream of `response.output_audio.delta` events (base64 24 kHz 16-bit mono PCM) alongside `response.output_audio_transcript.delta` text, ending with `response.done`. To talk instead of type, stream microphone audio with `input_audio_buffer.append` — with `server_vad` turn detection the model detects when you stop speaking and responds on its own, no `response.create` needed.

<Note>
  Building for the browser or mobile? Don't ship your API key: mint a short-lived key with `POST /v1/realtime/client_secrets` and connect with the `bai-client-secret.<key>` subprotocol (see [Authentication](/models/higgs-realtime/guides/connections-and-sessions#authentication)).
</Note>

## It didn't work?

<AccordionGroup>
  <Accordion title="No sound, or an audio device error">
    `sounddevice` plays through your system's default output device. Check that a working output device is selected and unmuted. The transcript print (`Assistant: …`) confirms the model replied even if playback failed.
  </Accordion>

  <Accordion title="Connection closes with code 3000">
    Invalid API key (or an invalid/expired ephemeral key). Check `BOSON_API_KEY` is set in the shell running the script and matches a key in your [workspace](https://www.boson.ai/workspace/api-key). See [Authentication](/authentication).
  </Accordion>

  <Accordion title="error event with type insufficient_quota, then close code 4429">
    A billing refusal — your key is fine, but the account has no available balance. New accounts must [claim their free trial credit](/free-trial-credit) first; otherwise [add credits](/account-billing/payment-and-credits) in [workspace billing](https://www.boson.ai/workspace/billing/overview). See [Common error types](/api-reference/errors).
  </Accordion>
</AccordionGroup>

## Go deeper

<CardGroup cols={2}>
  <Card title="Connections & sessions" icon="plug" href="/models/higgs-realtime/guides/connections-and-sessions">
    Session configuration, limits, and lifecycle.
  </Card>

  <Card title="Audio & voices" icon="waveform-lines" href="/models/higgs-realtime/guides/audio-and-voices">
    Audio formats, preset voices, and custom voices.
  </Card>

  <Card title="Turn detection & interruptions" icon="microphone-lines" href="/models/higgs-realtime/guides/turn-detection-and-interruptions">
    `server_vad`, `semantic_vad`, and barge-in.
  </Card>

  <Card title="Tool calling" icon="wrench" href="/models/higgs-realtime/guides/tool-calling">
    Let the model call your functions mid-conversation.
  </Card>

  <Card title="LiveKit & Pipecat" icon="puzzle-piece" href="/models/higgs-realtime/integrations/livekit">
    Production voice-agent frameworks with Higgs Realtime built in.
  </Card>

  <Card title="Migrate from OpenAI" icon="arrow-right-arrow-left" href="/models/higgs-realtime/migrate-an-existing-integration">
    The protocol is OpenAI Realtime compatible — most integrations move with config changes.
  </Card>
</CardGroup>