Introduction
Send the text to be read and, optionally, one of 30 voices, an accent, a style, a pace, a scene and a short note on delivery; for a conversation, send dialogue and speakers instead of text. The task returns one WAV file (24 kHz, 16-bit mono) with the script read in that voice, or in up to two voices for a dialogue, usually within seconds. Shape the reading with punctuation; bracketed cues such as [sighs] are not reliably performed and are sometimes read aloud. SpicyAPI applies no content filter, so every script is read as written. You are billed per second of the audio returned.
| Field | Value |
|---|---|
| Input | Text |
| Output | Audio |
| Required field | text (1 to 5,000 characters) or dialogue (up to 20 lines) |
| Optional fields |
|
| Result | One WAV file, 24 kHz, 16-bit, mono |
| Longest clip | 16,384 audio tokens |
| Billed quantity | Seconds of audio returned, measured from the file |
| Retention | Generated audio is kept for 14 days |
Request parameters
| Parameter | Required | Description |
|---|---|---|
text | No | The words to be spoken, exactly as written. Bracketed cues such as [sighs] are not reliably performed and may be read aloud; spell sounds out instead. at least 1 characters · at most 5000 characters |
dialogue | No | A scripted conversation for up to two voices, used instead of text: up to 20 lines, each with speaker (a name from speakers) and text of up to 250 characters. at least 1 items · at most 20 items |
speakers | No | The cast for dialogue: one or two entries, each with a name the lines refer to, a |
voice_id | No | One of 30 prebuilt voices, each with a fixed character. Defaults to Kore. |
style | No | Overall manner of the reading. Leave empty to use the voice's own default manner. |
pace | No | Rhythm of the reading: natural, |
accent | No | English accent for the reading. Omit it to use the voice's own accent. |
instructions | No | Free-text direction on how to read: pace, mood, distance from the microphone, who is listening. Shapes the delivery and is not spoken. at most 1000 characters |
scene | No | Where and to whom the words are spoken, such as “a quiet hotel room after midnight”. Shapes the delivery and is not spoken. at most 500 characters |
temperature | No | Variation between takes, from 0 to 2: higher values make the delivery less predictable. Leave it unset to use the model's default. |
Pricing
$0.00021 / second
Billed per second of audio returned. A hold for 660 seconds is placed while the task runs and the unused part is released when the audio is measured.
Use cases
High-volume narration
Product copy, lesson scripts, article read-outs and batches of short lines where turnaround and cost matter more than acting nuance.
Character and companion voices
Give a chat character a voice of its own and answer in seconds. Short, spoken-style sentences and careful punctuation carry most of the tone.
Uncensored audio stories
Scripts go through without a content filter. In our tests the model spoke every word of the boldest monologues and narrated scenes we sent, without skipping or cutting the clip short.
Voice tracks for video
Generate the line here, then hand the WAV to a talking-avatar or lip-sync model so a face performs it. The audio length sets the length of the clip downstream.
Prompt guide & pro tips
Send the script in text
Write it exactly as it should be spoken, including punctuation for pauses. Up to 5,000 characters.
Pick a voice
voice_iddefaults to Kore. Each of the 30 voices has a fixed character, so choose once and keep it for a series.Write sounds as sounds
For sighs, laughs or moans, spell them out — "Mmm…", "ha…", "ahh…" — rather than using bracketed tags, which this model sometimes reads aloud.
What it returns
One WAV file per task: 24 kHz, 16-bit, mono PCM. 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 30 prebuilt voices and defaults to Kore. Each voice has a fixed character — for example Kore firm, Charon informative, Puck upbeat, Enceladus breathy, Achernar soft, Algenib gravelly, Sulafat warm, Gacrux mature. The voice does not change with the language of the script.
Shaping the reading
Besides text and voice_id, these settings shape the reading:
style,accentandpaceset the manner, English accent and rhythm; leave them out and the voice keeps its own.instructionstakes free text about how to read, andscenesays where and to whom the words are spoken. Neither is spoken.temperature(0–2) sets how much the delivery varies between takes.
Punctuation still carries much of the delivery: commas and ellipses slow it down, short sentences make it more conversational.
Bracketed cues such as [sighs] are not reliably performed — in our tests the model sometimes read the word inside the brackets aloud. Spell sounds out instead ("Mmm…", "ahh…"). If performed cues matter, use Gemini 3.8 Flash TTS.
On this model, direction sent for a single voice can be read aloud at the start of the clip. So when a single-voice request carries style, accent, pace, instructions or scene, SpicyAPI sends it in the model's two-speaker format with a silent second speaker, which keeps the notes out of the audio. Billing is unchanged: you pay for the seconds returned.
Two voices in one clip
For a conversation, send dialogue instead of text, plus speakers with the cast: one or two entries, each with a name, a voice_id and optionally accent, style, pace and profile, a short description of who is speaking that is not read aloud. Each dialogue line is {speaker, text}, where speaker is one of those names; lines are performed in order, up to 20 lines of 250 characters each. Settings a speaker leaves out fall back to the top-level accent, style and pace. The whole conversation comes back as one WAV file, billed per second like any other request.
Length and timing
text accepts up to 5,000 characters. A 270-character paragraph came back as 22–26 seconds of audio in our tests, and the median task finished generating in about 7 seconds. The model stops at 16,384 audio tokens per clip.
Billing
Billed per second of audio returned, measured from the file. While the task runs, a hold for 660 seconds is placed on your balance and the unused part is released when the task settles. Failed requests are not charged.
Content
SpicyAPI adds no content filter. In our tests every script was read word for word, the boldest ones included, 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": "google/gemini-3.8-flash-lite-tts/text-to-speech",
"input": {
"text": "Welcome back. Your files finished rendering a minute ago and are ready to download.",
"voice_id": "Kore"
}
}'
# 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.
