Introduction
Send the text to be read, a system voice, an emotion and, optionally, a language hint. The task returns one audio file with the script read in that voice and emotion: a 32 kHz mono MP3 unless you set output_format, sample_rate, bitrate or audio_channels. speed, pitch and volume adjust the delivery, and pronunciation_dict fixes how specific words are read. Sound tags in parentheses such as (sighs) or (laughs) placed in text are performed as sounds, not read aloud. SpicyAPI applies no content filter; the script is read exactly as sent. You are billed per 1,000 characters of the text you send.
| Field | Value |
|---|---|
| Input | Text |
| Output | Audio |
| Required field | text — 1 to 5,000 characters |
| Optional fields |
|
| Result | One audio file: MP3 (32 kHz mono) by default, or WAV, FLAC, PCM |
| Billed quantity | Characters of text sent, per 1,000 |
| Typical time | About 8 seconds for 300 characters |
| Retention | Generated audio is kept for 14 days |
Request parameters
| Parameter | Required | Description |
|---|---|---|
text | Yes | The words to be spoken, exactly as written. Sound tags in parentheses such as (sighs) or (laughs) are performed as sounds, not read aloud. at least 1 characters · at most 5000 characters |
voice_id | No | One of 472 system voices. Defaults to Calm_Woman. |
emotion | No | One of seven fixed emotions — neutral, happy, sad, angry, fearful, disgusted or surprised — applied to the whole reading. Defaults to neutral. |
speed | No | Speaking rate from 0.5 (slower) to 2 (faster); 1 is the voice's normal pace. Does not change the price. |
pitch | No | Pitch shift in semitones, from -12 to 12; 0 keeps the voice's own pitch. Does not change the price. |
volume | No | Loudness multiplier from 0.1 to 10; 1 is the normal level. Does not change the price. |
language | No | A hint that improves pronunciation for one of 40 languages. Defaults to auto, which detects the language from the script. |
output_format | No | File format: mp3 (default), wav, flac, or pcm, which is raw 16-bit little-endian samples with no header at the chosen |
sample_rate | No | Sample rate of the audio in Hz: 8000, 16000, 22050, 24000, 32000, 44100. Defaults to 32000. |
bitrate | No | MP3 bitrate in bits per second: 32000, 64000, 128000 or 256000. Defaults to 128000 and only applies when |
audio_channels | No | Output channels: mono (default) or stereo. Does not change the price. |
english_normalization | No | When on, numbers, dates and abbreviations in English text are read the way a person would say them, such as 1990 as “nineteen ninety”. Off by default. Default: |
pronunciation_dict | No | Up to 100 {alias, pronunciation} pairs. Every occurrence of alias in text is read as pronunciation: plain words (Omg → Oh my god) or IPA in parentheses such as (rɪˈzjuːm). at most 100 items |
Pricing
$0.072 / 1,000 characters
Billed per 1,000 characters of text sent, counting spaces and punctuation. The quote before the run is the final price.
Use cases
Voice-overs for short videos
Narration for explainers, product clips and social posts. The price is fixed by the script length, so you know what a batch costs before you start.
Multilingual content
Read the same script with a language hint for any of 40 supported languages, or leave it on auto and let the script decide.
Uncensored audio stories
There is no content filter on the script. In our tests the model spoke every word of the boldest monologues and narrated scenes we tried, performing breath and sound cues instead of reading them aloud.
Emotional character reads
Set one of seven emotions per request — happy, sad, angry, fearful, disgusted or surprised — and let (sighs), (laughs) or (breath) tags in the script shape the performance.
Prompt guide & pro tips
Send the script in text
Write it exactly as it should be spoken, with punctuation for pauses and sound tags such as (sighs) in parentheses where you want them performed. Up to 5,000 characters.
Pick a voice and emotion
voice_iddefaults to Calm_Woman; emotion defaults to neutral and takes one of seven fixed values.Add a language hint if needed
Leave language on auto to detect it from the script, or set one of 40 languages when a short or mixed script needs help with pronunciation.
What it returns
One audio file per task: a 32 kHz mono MP3 unless you set output_format, sample_rate, bitrate or audio_channels. The file is copied to SpicyAPI storage and kept for 14 days.
Choosing a voice
voice_id takes one of 472 system voices, such as Calm_Woman, Deep_Voice_Man, Lively_Girl or Elegant_Man, and defaults to Calm_Woman. There is no cloning and no upload of a reference voice.
Setting an emotion
emotion takes one of seven fixed values — neutral, happy, sad, angry, fearful, disgusted or surprised — and applies to the whole reading. It defaults to neutral.
Sound tags
Tags placed in parentheses inside text, such as (sighs), (laughs), (breath) or (gasps), are performed as sounds rather than read aloud. In our tests this held for the boldest scripts as well as ordinary ones.
Language
The language is detected from the script. language hints one of 40 languages, including Mandarin, Cantonese, English, Arabic, Russian, Spanish, French, Portuguese, German, Japanese, Italian, Korean, Polish and more, to improve pronunciation on a short or mixed script.
Delivery controls
speed (0.5–2), pitch (-12 to 12 semitones) and volume (0.1–10) adjust the reading without changing the price. pronunciation_dict takes up to 100 {alias, pronunciation} pairs, so a name, acronym or loanword is always read the way you want: plain words or IPA in parentheses. english_normalization reads numbers, dates and abbreviations in English text the way a person would say them.
Output format
output_format picks mp3 (default), wav, flac or pcm; sample_rate goes from 8000 to 44100 Hz, bitrate sets the MP3 bitrate and audio_channels switches to stereo. pcm is raw 16-bit little-endian samples with no header, so it cannot be previewed in a browser; choose wav if you want the same samples in a playable file.
Billing
Billed per 1,000 characters of text, counting spaces, punctuation and line breaks. The character count is known before the task starts, so the quote is the final charge. Failed requests are not charged.
Content
SpicyAPI adds no content filter. In our tests every script was read word for word, however strong, with sound tags performed as written and nothing skipped.
SpicyAPI adds no content filter: NSFW scripts are read as written. You are responsible for the scripts you send and for how you use the resulting audio, including not passing it off as a real person's words.
API quick start
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "minimax/speech-2.8-turbo/text-to-speech",
"input": {
"text": "Welcome back. Your files finished rendering a minute ago and are ready to download.",
"emotion": "neutral",
"language": "auto",
"voice_id": "Calm_Woman",
"output_format": "mp3"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
See the API reference for authentication, the complete schema, polling, and error handling.
