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

# StepAudio 2.5 Realtime

StepAudio 2.5 Realtime is an end-to-end speech-to-speech model served over a WebSocket Realtime API. It takes streaming audio or text and responds with streaming audio and a matching text transcript, with no separate speech-to-text or text-to-speech stage in between. It understands both the words and the tone behind them, such as hesitation, a slight laugh, or frustration, and replies with natural, expressive speech in real time.

## Specifications

> [card] Model ID
>
> `stepaudio-2.5-realtime`

> [card] Endpoint
>
> `wss://api.stepfun.ai/v1/realtime` (WebSocket)

> [card] Input
>
> Audio or text

> [card] Output
>
> Audio and text

> [card] Audio format
>
> PCM16, 24 kHz, mono

> [card] Languages
>
> English

## Capabilities

* **Speech-to-speech in real time**: Audio flows in and out over a single WebSocket connection, so the model replies with spoken audio directly instead of routing through separate transcription and synthesis steps. This keeps latency low enough for natural back-and-forth conversation.
* **Paralinguistic understanding**: For audio input, the model interprets vocal cues such as intonation, pacing, hesitation, and laughter in addition to the spoken words, capturing a speaker's emotional state and intent that a plain transcript does not represent.
* **Natural turn-taking**: Server-side voice activity detection (VAD) detects when the speaker starts and stops talking, so the model can reply at the right moment and be interrupted mid-response, the way a person can.
* **Persona and style control**: Session instructions define the assistant's personality, speaking style, and boundaries, and can shape audio behavior such as keeping replies short or speaking warmly, maintaining a consistent voice throughout a conversation.

### Common use cases

* **Voice agents for customer support**: Handle spoken customer conversations end to end, reading tone and intent and responding with natural speech for support, account servicing, and triage.
* **Live assistants**: Power hands-free assistants that listen and reply in real time for scheduling, guidance, and question answering.
* **Interactive phone and IVR systems**: Replace rigid menu trees with a conversational agent that callers can speak to naturally and interrupt at any time.

## Voices

The following system voices are available. Set the voice with `session.update` before the model produces audio.

| Voice ID | Voice |
| :- | :- |
| `soft-spoken-gentleman` | Calm, gentle male voice |
| `magnetic-voiced-male` | Deep, magnetic male voice |
| `vibrant-youth` | Youthful, energetic voice |
| `lively-girl` | Bright, lively female voice |
| `livelybreezy-female` | Light, breezy female voice |
| `elegantgentle-female` | Elegant, gentle female voice |
| `zixinnansheng` | Confident male voice |

> [!NOTE]
>
> Always set `voice` explicitly in `session.update`. Only the voice IDs listed above are valid for this model; other values are rejected with a `400` error. A session's voice cannot be changed once the model has produced audio.

## Quick Start

This section walks you through your first Realtime session, from creating an API key to sending a turn and saving the spoken reply.

### Set up your environment

**1. Create an API key**

Create a key on the [StepFun API platform](https://platform.stepfun.ai/interface-key).

**2. Set your API key as an environment variable**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
export STEPFUN_API_KEY="YOUR_STEP_API_KEY"
```

**3. Install a WebSocket client**

```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
pip install websocket-client
```

All sessions connect to `wss://api.stepfun.ai/v1/realtime`, with the model passed as a query parameter.

### Send a spoken turn and receive a spoken reply

This example downloads a sample customer question (a short English audio clip), streams it to the model as audio input, and saves the model's spoken reply to a WAV file.

```python theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
import os
import json
import base64
import wave
import urllib.request
from io import BytesIO
import websocket  # pip install websocket-client

URL = "wss://api.stepfun.ai/v1/realtime?model=stepaudio-2.5-realtime"
SAMPLE_AUDIO_URL = "https://static-openapi.stepfun.ai/static/platform-docs/resource/1782215968301_hza73c.wav"  # sample English customer question (24 kHz mono WAV)

# Download the sample question and read its PCM16 samples (24 kHz, mono).
wav_bytes = urllib.request.urlopen(SAMPLE_AUDIO_URL).read()
with wave.open(BytesIO(wav_bytes), "rb") as wf:
    pcm = wf.readframes(wf.getnframes())

reply = bytearray()

def on_open(ws):
    # Configure the session: respond with text and audio, in English.
    ws.send(json.dumps({
        "type": "session.update",
        "session": {
            "modalities": ["text", "audio"],
            "instructions": "You are a warm, professional customer-support voice agent. Acknowledge how the customer feels, then help. Keep replies short.",
            "voice": "soft-spoken-gentleman",
            "input_audio_format": "pcm16",
            "output_audio_format": "pcm16",
        },
    }))
    # Stream the caller's audio, commit it as a turn, then ask the model to respond.
    audio_b64 = base64.b64encode(pcm).decode()
    for i in range(0, len(audio_b64), 32000):
        ws.send(json.dumps({"type": "input_audio_buffer.append", "audio": audio_b64[i:i + 32000]}))
    ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
    ws.send(json.dumps({"type": "response.create"}))

def on_message(ws, message):
    event = json.loads(message)
    if event["type"] == "conversation.item.input_audio_transcription.completed":
        print("Caller said:", event["transcript"])           # the model's transcript of the input
    elif event["type"] == "response.audio.delta":
        reply.extend(base64.b64decode(event["delta"]))        # streamed PCM16 audio
    elif event["type"] == "response.audio_transcript.done":
        print("Assistant:", event["transcript"])              # text of the spoken reply
    elif event["type"] == "response.done":
        ws.close()

ws = websocket.WebSocketApp(
    URL,
    header=[f"Authorization: Bearer {os.environ['STEPFUN_API_KEY']}"],
    on_open=on_open,
    on_message=on_message,
)
ws.run_forever()

# Save the spoken reply (PCM16, 24 kHz, mono) as a playable WAV file.
with wave.open("reply.wav", "wb") as f:
    f.setnchannels(1)
    f.setsampwidth(2)
    f.setframerate(24000)
    f.writeframes(bytes(reply))
```

## Pricing

Realtime sessions are billed by tokens: \$1.50 per 1M input tokens and \$10.00 per 1M output tokens. See the [pricing page](https://platform.stepfun.ai/docs/en/guides/pricing/details.md) for details.

## Related Resources

> [card] [Audio Models Overview](https://platform.stepfun.ai/docs/en/guides/models/audio.md)
>
> Compare all speech models and choose the right one.

> [card] [StepAudio 2.5 Chat](https://platform.stepfun.ai/docs/en/guides/models/stepaudio-2.5-chat)
>
> Speech understanding over the Chat Completion API when you do not need streaming audio output.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.