Introduction
Send the text to be read and, optionally, a preset voice, a short note on delivery and a language. The task returns one audio file with the script read in that voice: a 24 kHz mono MP3 unless you set output_format or sample_rate. speed, pitch and volume adjust the delivery. instructions takes plain-language direction such as tone, emotion, pace or volume and is not read aloud. SpicyAPI applies no content filter, so the script you send is the script you hear. 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 (24 kHz mono) by default, or Ogg Opus |
| 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. Billed per 1,000 characters, including spaces and punctuation. at least 1 characters · at most 5000 characters |
voice_id | No | One of 41 preset voices. The suffix shows the languages the voice is built for. |
instructions | No | Plain-language direction on tone, emotion, pace or volume. Shapes the delivery and is not spoken. at most 1000 characters |
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.5 to 2; 1 is the normal level. Does not change the price. |
language | No | Forces the reading language. Leave empty to detect it from the script. |
output_format | No | File format: mp3 (default) or opus, an Ogg Opus file that is smaller at the same quality. Does not change the price. |
sample_rate | No | Sample rate of the audio in Hz: 8000, 16000, 22050, 24000, 32000, 44100, 48000. Defaults to 24000. |
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 in English, Japanese, Spanish, German and more. Several voices are built to speak more than one language in the same timbre.
Uncensored audio stories
Scripts are voiced as written, however bold. In our tests the model spoke every word of the strongest monologues and narrated scenes we sent, without skipping or cutting the clip short.
Character voices
Give each character a preset voice and a one-line note on how they talk — breathless, sleepy, teasing — and keep both for the whole series.
Prompt guide & pro tips
Send the script in text
Write it exactly as it should be spoken, with punctuation for pauses. Up to 5,000 characters.
Pick a voice
voice_iddefaults tostokie_en. The suffix of each voice shows the languages it is built for, for example _en or _ja_es.Describe the delivery
Put a sentence or two in instructions — for example 'slow, low and close, as if speaking to one person'. It is not read aloud.
What it returns
One audio file per task: a 24 kHz mono MP3 unless you set output_format or sample_rate. 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 41 preset voices and defaults to stokie_en. The suffix of each voice name lists the languages it is built for — tim_en is English, minimi_ja Japanese, sven_de German, jess_ja_es_id_pt_en_zh speaks several. Mixed voices keep the same timbre across their languages.
Directing the delivery
instructions takes a sentence or two of plain language about how to read: tone, emotion, pace, volume. It shapes the performance and is not spoken. For exact control, speed (0.5–2), pitch (-12 to 12 semitones) and volume (0.5–2) have their own sliders.
Output format
output_format picks mp3 (default) or opus, an Ogg Opus file that is smaller at the same quality, and sample_rate goes from 8000 to 48000 Hz. None of these change the price.
Language
The language is detected from the script. language forces one of zh, en, ja, es-mx, id, pt-br, ko, it, de or fr when a short or mixed script is read in the wrong one.
Billing
Billed per 1,000 characters of text, counting spaces, punctuation and line breaks; instructions is free. 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 even the strongest scripts were voiced word for word, with nothing skipped and no clip ended early.
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": "bytedance/seed-speech-2.0/text-to-speech",
"input": {
"text": "Welcome back. Your files finished rendering a minute ago and are ready to download.",
"voice_id": "stokie_en",
"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.