Text-to-Speech Implementation Guide - SambaNova Documentation

Qwen3-TTS is a preview feature available for SambaStack users only. Preview features may change before general availability.

SambaStack provides text-to-speech (TTS) capabilities through the qwen3-tts model, which converts text input into streaming PCM audio. The model supports 11 languages.

Qwen3-TTS

Model ID: qwen3-tts
Provider: Qwen (Alibaba Cloud)
Endpoint: POST /v1/audio/speech
Status: Preview

Supported voices

The voice parameter is accepted for API compatibility but is currently ignored. Audio is always generated using the reference voice configured at deployment time.

Voice ID	Description
`serena`	Female
`vivian`	Female
`uncle_fu`	Male
`ryan`	Male
`aiden`	Male
`ono_anna`	Female
`sohee`	Female
`eric`	Male
`dylan`	Male

Supported languages

Language	Accepted values
Auto (detect)	`auto`
Chinese	`Chinese`, `zh`, `cn`, `chi`
English	`English`, `en`, `eng`
French	`French`, `fr`, `fra`, `fre`
German	`German`, `de`, `ger`
Italian	`Italian`, `it`, `ita`
Japanese	`Japanese`, `ja`, `jp`, `jpn`
Korean	`Korean`, `ko`, `kor`
Portuguese	`Portuguese`, `pt`, `por`
Russian	`Russian`, `ru`, `rus`
Spanish	`Spanish`, `es`, `spa`

Language matching is case-insensitive. If you omit the language parameter, it defaults to english.

Request parameters

Parameter	Type	Required	Description
`model`	string	Yes	Must be `qwen3-tts`.
`input`	string	Yes	Text to synthesize into speech.
`voice`	string	No	Speaker voice ID. Accepted for API compatibility; any value is currently ignored. See Supported voices.
`stream`	boolean	Yes	Must be `true`. Non-streaming responses are not yet supported.
`language`	string	No	Language of the input text. Default: `english`. See Supported languages.
`instructions`	string	No	Instructions to influence speaking style. Maximum 512 characters.
`sampling_params`	object	No	Sampling configuration. Accepted keys: `temperature`, `top_k`, `top_p`, `seed`. Example: `{"temperature": 0.8, "seed": 42}`.

Example usage

import base64
import json
import struct
import wave
import requests

url = "https://your-sambanova-base-url/v1/audio/speech"
headers = {
    "Authorization": "Bearer your-sambanova-api-key",
    "Content-Type": "application/json",
}
payload = {
    "model": "qwen3-tts",
    "input": "Hello, welcome to SambaNova.",
    "voice": "serena",
    "language": "english",
    "stream": True,
}

pcm_frames = []

with requests.post(url, headers=headers, json=payload, stream=True) as resp:
    resp.raise_for_status()
    for line in resp.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        data = line[len(b"data: "):]
        if data == b"[DONE]":
            break
        event = json.loads(data)
        if event.get("finish_reason") == "error":
            raise RuntimeError(f"Stream error: {event.get('error')}")
        audio_b64 = event.get("audio_b64", "")
        if audio_b64:
            pcm_frames.append(base64.b64decode(audio_b64))
        if event.get("finish_reason") == "stop":
            break

# Write f32le PCM frames to a WAV file
pcm_bytes = b"".join(pcm_frames)
num_samples = len(pcm_bytes) // 4  # 4 bytes per f32 sample
samples = struct.unpack(f"{num_samples}f", pcm_bytes)
pcm_int16 = bytes(
    struct.pack("<h", max(-32768, min(32767, int(s * 32767)))) for s in samples
)

with wave.open("output.wav", "wb") as wf:
    wf.setnchannels(1)
    wf.setsampwidth(2)  # 16-bit
    wf.setframerate(24000)
    wf.writeframes(pcm_int16)

print("Saved output.wav")

# This command shows the raw SSE stream. Use the Python example to produce a playable audio file.
curl -X POST https://your-sambanova-base-url/v1/audio/speech \
  -H "Authorization: Bearer your-sambanova-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-tts",
    "input": "Hello, welcome to SambaNova.",
    "voice": "serena",
    "language": "english",
    "stream": true
  }'

Response format

The endpoint streams a Server-Sent Events (SSE) response. Each event is a JSON object on a data: line. Response headers

Header	Value	Description
`Content-Type`	`text/event-stream`	SSE stream
`X-Audio-Format`	`f32le`	32-bit float, little-endian PCM
`X-Audio-Sample-Rate`	`24000`	24 kHz sample rate
`X-Audio-Channels`	`1`	Mono

Event fields

Field	Type	Description
`audio_b64`	string	Base64-encoded PCM audio chunk.
`chunk_index`	integer	Sequential index of the audio chunk.
`finish_reason`	string \| null	`null` while streaming; `"stop"` on the final chunk; `"error"` if the stream fails mid-way.
`id`	string	Request identifier.
`object`	string	Always `audio.speech.chunk`.
`created`	integer	Unix timestamp.

Example event

{
  "audio_b64": "<base64-encoded PCM data>",
  "chunk_index": 0,
  "finish_reason": null,
  "id": "abc123",
  "object": "audio.speech.chunk",
  "created": 1750000000
}

Final event

{
  "audio_b64": "<base64-encoded PCM data>",
  "chunk_index": 12,
  "finish_reason": "stop",
  "id": "abc123",
  "object": "audio.speech.chunk",
  "created": 1750000000
}

Limitations

Streaming only: stream: false is not supported. All responses are SSE streams.
Concurrency: The model processes one request at a time. Concurrent requests queue behind the active request.
Maximum audio length: 320 seconds per request. If the input text is long enough to exceed this limit, the response ends at the cap – no error is returned. For longer audio, split the text into smaller passages and send separate requests.
Mid-stream audio artifacts: Longer audio clips may contain audible artifacts partway through the stream. If you encounter this, split the input into shorter passages and send separate requests.
No context cache: Each request is stateless.

​Qwen3-TTS

​Supported voices

​Supported languages

​Request parameters

​Example usage

​Response format

​Limitations

Qwen3-TTS

Supported voices

Supported languages

Request parameters

Example usage

Response format

Limitations