Endpoint POST /v1/audio/stream
Authentication Bearer token required
Overview
The streaming endpoint converts text to speech and streams MP3 audio in real-time. This endpoint is ideal for applications requiring low-latency audio playback, such as real-time assistants or live caption-to-speech conversion.
Response Format audio/mpeg (chunked MP3)
First Byte Latency < 500ms
Request Parameters
The text to convert to speech. Maximum 5,000 characters.
The synthesis model to use. Currently supported: legacy-v2.5
Adjust the voice pitch. Range: -100% to +100%.
Default: +0%
Emotional speaking style. Options: neutral, cheerful,
calm, angry, sad, excited,
whispering. Default: calm
Intensity of the selected style. Range: 0.5 to 2.0.
Default: 1.5
BCP-47 language code (e.g., en-US, fr-FR). Default:
en-US
Examples
curl
Node.js
Python
JavaScript (Browser)
curl -X POST https://api.suonora.com/v1/audio/stream \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
--output - \
-d '{
"input": "Welcome to Suonora streaming!",
"model": "legacy-v2.5",
"voice": "axel",
"style": "cheerful",
"styleDegree": 1.2
}' | ffplay -autoexit -nodisp -
const Suonora = require ( 'suonora-sdk' );
const { createWriteStream } = require ( 'fs' );
const { pipeline } = require ( 'stream/promises' );
const suonora = new Suonora ({
apiKey: 'YOUR_API_KEY'
});
async function streamSpeech () {
try {
const stream = await suonora . audio . stream ({
input: "Welcome to Suonora streaming!" ,
model: "legacy-v2.5" ,
voice: "axel" ,
style: "cheerful" ,
styleDegree: 1.2
});
// Pipe to file or audio player
await pipeline (
stream ,
createWriteStream ( "output.mp3" )
);
console . log ( "Stream completed" );
} catch ( error ) {
console . error ( "Error:" , error . message );
}
}
streamSpeech ();
import requests
import sys
url = "https://api.suonora.com/v1/audio/stream"
headers = {
"Authorization" : "Bearer YOUR_API_KEY" ,
"Content-Type" : "application/json"
}
data = {
"input" : "Welcome to Suonora streaming!" ,
"model" : "legacy-v2.5" ,
"voice" : "axel" ,
"style" : "cheerful" ,
"styleDegree" : 1.2
}
try :
with requests.post(url, json = data, headers = headers, stream = True ) as response:
response.raise_for_status()
# Stream to file
with open ( "output.mp3" , "wb" ) as f:
for chunk in response.iter_content( chunk_size = 8192 ):
if chunk:
f.write(chunk)
# Optional: Process chunk in real-time
sys.stdout.buffer.write(chunk)
sys.stdout.buffer.flush()
except requests.exceptions.RequestException as e:
print ( f "Error: { e } " )
async function streamSpeech () {
try {
const response = await fetch ( "https://api.suonora.com/v1/audio/stream" , {
method: "POST" ,
headers: {
"Authorization" : "Bearer YOUR_API_KEY" ,
"Content-Type" : "application/json"
},
body: JSON . stringify ({
input: "Welcome to Suonora streaming!" ,
model: "legacy-v2.5" ,
voice: "axel" ,
style: "cheerful" ,
styleDegree: 1.2
})
});
if ( ! response . ok ) {
throw new Error ( `HTTP error! status: ${ response . status } ` );
}
// Set up MediaSource for streaming playback
const mediaSource = new MediaSource ();
const audio = document . getElementById ( 'player' );
audio . src = URL . createObjectURL ( mediaSource );
mediaSource . addEventListener ( 'sourceopen' , async () => {
const sourceBuffer = mediaSource . addSourceBuffer ( 'audio/mpeg' );
const reader = response . body . getReader ();
while ( true ) {
const { done , value } = await reader . read ();
if ( done ) {
mediaSource . endOfStream ();
break ;
}
// Append chunk to source buffer
await new Promise ( resolve => {
sourceBuffer . appendBuffer ( value );
sourceBuffer . addEventListener ( 'updateend' , resolve , { once: true });
});
}
});
// Start playback
audio . play ();
} catch ( error ) {
console . error ( "Error:" , error );
}
}
Response
The endpoint streams MP3 audio data with the following headers:
Error Responses
Best Practices
Connection Management : Use HTTP/2 or keep-alive connections to reduce latency
Back-pressure : Process chunks as they arrive to maintain stream health
Error Recovery : Implement reconnection logic for network interruptions
Browser Support : Use MediaSource API for optimal browser streaming
Security : Keep your API key secure and never expose it in client-side code
Streaming vs Standard Endpoint
Use Streaming When
Real-time playback is needed - Low latency is critical - Processing long
texts - Building conversational apps
Use Standard When
Saving audio to files - Offline caching - Simple playback - Short text
snippets