Introduction
Send the text to be read and, optionally, a voice, a language, a speed and an output format. The task returns one audio file — MP3 at 24 kHz by default — with the script read in that voice. Speech tags written into the text, such as [laugh] or …, are acted out rather than read. SpicyAPI applies no content filter, and scripts are read as written. You are billed per 1,000 characters of the text you send.
| Field | Value |
|---|---|
| Input | Text |
| Output | Audio |
| Required field | text — 1 to 15,000 characters, speech tags allowed |
| Optional fields |
|
| Result | One audio file; MP3, 24 kHz, 128 kbps, mono by default |
| Billed quantity | Characters of text sent, per 1,000, tags included |
| Typical time | 3 to 8 seconds for 170 to 320 characters |
| Retention | Generated audio is kept for 14 days |
Request parameters
| Parameter | Required | Description |
|---|---|---|
text | Yes | The words to be spoken, exactly as written, with optional speech tags such as [laugh] or …. 1 to 15,000 characters. at least 1 characters · at most 15000 characters |
voice_id | No | One of 71 preset voices, labelled with name, gender and language. Eve (default), Ara, Leo, Rex and Sal speak every supported language; the others are tuned for one language. |
language | No | The reading language as a language code, or auto (default) to detect it from the script. Set it when a short or mixed script comes out in the wrong language. |
speed | No | Speaking speed from 0.7 (slower) to 1.5 (faster); default 1.0. Does not change the price. |
output_format | No | Audio encoding: mp3 (default), wav, or the header-less streams pcm, mulaw and alaw for phone systems. Does not change the price. |
sample_rate | No | Sample rate in Hz: 8000, 16000, 22050, 24000 (default), 44100 or 48000. Use 8000 with mulaw or alaw for phone lines, 44100 or 48000 for studio work. |
bitrate | No | MP3 bit rate in bits per second: 32000 to 192000, default 128000. Only applies when |
text_normalization | No | When on, written forms such as numbers, abbreviations and symbols are converted to their spoken form before reading. Off by default. Default: |
optimize_streaming_latency | No | Streaming latency level from the model: 0 (default) keeps the best audio quality; 1 uses a smaller first audio chunk for lower time-to-first-audio, with a minor quality trade-of… |
Pricing
$0.018 / 1,000 characters
Billed per 1,000 characters of text sent, counting spaces, punctuation and speech tags. The quote before the run is the final price.
Use cases
Voice notes and companion apps
Whispered asides, a laugh in the right place, a breath before the next line — written into the script as tags, so the delivery is part of the text you store and replay.
Audiobooks and serial fiction
Up to 15,000 characters in one request, a narrator voice that stays the same across chapters, and a speed slider for a slower bedtime read. No chapter is filtered or softened on the way.
Multilingual narration
Read the same script in English, Japanese, French, Korean, Arabic and more, either with one of the five multilingual voices or with a native voice for each language.
Phone lines and voice menus
Ask for 8 kHz μ-law or A-law and the audio arrives in the format a phone system plays directly, with no conversion step.
Prompt guide & pro tips
Write the script in text
Up to 15,000 characters. Put [pause], [laugh], [breath] or … exactly where you want them; punctuation shapes the rhythm.
Pick a voice and a language
voice_iddefaults to eve. Eve, Ara, Leo, Rex and Sal speak every supported language; the other voices are tuned for one. Leave language on auto unless a short or mixed script comes out in the wrong one.Set the pace and the format
speed runs from 0.7 to 1.5. Keep
output_formaton mp3 for playback, choose wav for editing, or pcm, mulaw and alaw at 8 kHz for phone systems.
What it returns
One audio file per task — MP3 at 24 kHz, 128 kbps, mono unless you ask otherwise. The file is copied to SpicyAPI storage and kept for 14 days. There are no word timings or subtitles in the result.
Choosing a voice
voice_id takes one of 71 preset voices and defaults to eve. Eve, Ara, Leo, Rex and Sal speak every supported language. The other 66 are each tuned for one language — Mandarin, Russian, Italian, Hindi, French, Spanish, Danish, Vietnamese, English, Swedish, Finnish, Turkish, Japanese, Korean, Portuguese, Dutch, Polish, Thai, Arabic or German — and read best in it. The form lists every voice with its name, gender and language.
Directing the delivery with tags
Write the performance into text. Instant tags make one sound at that point: [pause], [long-pause], [hum-tune], [laugh], [chuckle], [giggle], [cry], [tsk], [tongue-click], [lip-smack], [breath], [inhale], [exhale], [sigh]. Wrapping tags change the words inside them: <soft>, <whisper>, <loud>, <build-intensity>, <decrease-intensity>, <higher-pitch>, <lower-pitch>, <slow>, <fast>, <sing-song>, <singing>, <laugh-speak>, <emphasis>. The tags we tried were acted out and never read out as words.
Speed, language and format
speed runs from 0.7 to 1.5. language is detected when left on auto; set it when a short or mixed script comes out in the wrong one. output_format is mp3 by default; wav suits editing, and pcm, mulaw and alaw are header-less streams for phone systems — pair them with sample_rate 8000. bitrate only affects MP3. optimize_streaming_latency (0, 1 or 2) is the model's streaming latency level: higher levels make the first audio chunk smaller at a possible cost in quality at chunk boundaries; 0 keeps the best quality.
Billing
Billed per 1,000 characters of text, counting spaces, punctuation, line breaks and tags. The count is known before the task starts, so the quote is the final charge. Voice, language, speed and format do not change the price. Failed requests are not charged.
Content
SpicyAPI adds no content filter. In our tests the strongest scripts we sent were read word for word, with nothing skipped and no clip cut short.
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": "xai/grok-tts/text-to-speech",
"input": {
"text": "Welcome back. Your files finished rendering a minute ago and are ready to download.",
"bitrate": 128000,
"language": "auto",
"voice_id": "eve",
"sample_rate": 24000,
"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.
