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. Inside the script, cues in square brackets such as [whispering], [sighs] or [laughing] are acted out rather than read, and punctuation sets the pauses. SpicyAPI applies no content filter: scripts the official app would block are 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. Cues in square brackets such as [whispering] or [sighs] are performed, not read. 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.00032 / 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
Audiobooks and long-form narration
Chapters, bedtime stories and serialised fiction read by a steady narrator. Pick a voice once and keep it: the same voice sounds consistent from one chapter to the next.
Character and companion voices
Give a chat character a voice of its own. A [whispering] cue and short, spoken-style sentences turn plain text into lines that sound meant for one listener.
Uncensored audio stories
Unfiltered scripts are read as written. In our tests the model spoke every word of the monologues and narration we sent, and performed bracketed cues such as sighs and gasps rather than reading the tags.
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 the direction into the script
Put cues in square brackets where they should happen — [whispering], [sighs], [laughing], [gasping]. They are performed, not read 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.
Directing the delivery
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.
Inside text itself:
- Cues in square brackets such as
[whispering],[sighs],[laughing]or[gasping]are acted out rather than read aloud. - Commas, ellipses and full stops set the pauses.
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 20–24 seconds of audio in our tests. The model stops at 16,384 audio tokens per clip. Most tasks finish in under a minute.
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 unfiltered scripts were read word for word, and bracketed cues such as sighs and gasps were performed rather than read.
SpicyAPI adds no content filter: scripts are read as written, with nothing softened. 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-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.
