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

<Columns cols={2}>
  <Card title="Model ID">`stepaudio-2.5-realtime`</Card>
  <Card title="Endpoint">`wss://api.stepfun.ai/v1/realtime` (WebSocket)</Card>
  <Card title="Input">Audio or text</Card>
  <Card title="Output">Audio and text</Card>
  <Card title="Audio format">PCM16, 24 kHz, mono</Card>
  <Card title="Languages">English</Card>
</Columns>

## 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.
</Note>

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

<Steps>
  <Step title="Create an API key">
    Create a key on the [StepFun API platform](https://platform.stepfun.ai/interface-key).
  </Step>

  <Step title="Set your API key as an environment variable">
    ```bash theme={null}
    export STEPFUN_API_KEY="your-api-key"
    ```
  </Step>

  <Step title="Install a WebSocket client">
    ```bash theme={null}
    pip install websocket-client
    ```
  </Step>
</Steps>

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={null}
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](/docs/en/guides/pricing/details) for details.

## Related Resources

<Columns cols={2}>
  <Card title="Audio Models Overview" icon="layer-group" href="/docs/en/guides/models/audio">
    Compare all speech models and choose the right one.
  </Card>

  <Card title="StepAudio 2.5 Chat" icon="comment" href="/docs/en/guides/models/stepaudio-2.5-chat">
    Speech understanding over the Chat Completion API when you do not need streaming audio output.
  </Card>
</Columns>