First Synthesis with Sonus TTS

Turn text into natural speech with a single call to POST https://api.sagea.space/v1/audio/speech.

Synthesize text to MP3 with the nova voice
Save audio bytes to disk with curl and Python
Probe duration and format with ffprobe

Time to complete: ~10 minutes

Prerequisites

Python 3.9+ and pip install requests for the Python samples.
curl and ffprobe (ffmpeg) installed for audio inspection.
A SAGEA API key exported as SAGEA_API_KEY.
Read Synthesize speech with Sonus for the basics.
Skim the Sonus TTS model card for voices and formats.

Step 1: Synthesize your first line

Synthesize up to 4096 characters with model sonus-tts using voice nova, format mp3, and a friendly tone.

curl -X POST https://api.sagea.space/v1/audio/speech \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "sonus-tts", "input": "Welcome to SAGEA. This is your first Sonus synthesis.", "voice": "nova", "response_format": "mp3", "emotion": "friendly", "speed": 1.0}' \
  --output hello.mp3

Run it with pip install requests then python first_synthesis.py and ls -lh hello.mp3.

Step 2: Probe duration with ffprobe

Confirm valid MP3 audio and check duration:

ffprobe -v error -show_entries format=duration,size -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 hello.mp3

You should see codec_name=mp3 and a matching duration. Sonus supports 16kHz, 24kHz, and 44.1kHz.

Step 3: Try emotion and speed

Valid emotions are neutral, friendly, professional, excited, calm, and warm.

curl -X POST https://api.sagea.space/v1/audio/speech \
  -H "Authorization: Bearer $SAGEA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "sonus-tts", "input": "Your order is confirmed. We will notify you when it ships.", "voice": "nova", "response_format": "mp3", "emotion": "professional", "speed": 1.0}' \
  --output order.mp3

Supported formats are mp3, wav, ogg, and flac. Pricing is $15 per 1M chars for standard voices.

Verify

Play hello.mp3 locally. If the call fails, check the error table below.

Error	Cause	Fix
`401 Unauthorized`	API key missing or invalid	Run `echo $SAGEA_API_KEY` and re-export a valid key
`400 text_too_long`	Input exceeds 4096 chars	Split text into chunks under 4096 chars at sentence boundaries
`422 voice_not_found`	Voice name is misspelled	Use `nova` or a valid cloned `voice_id` starting with `vox_`
`429 rate_limit_exceeded`	Over 50 req per min on Starter, 500 on Pro	Back off and retry, or batch requests