Introduction
Send the text to be read and, optionally, a voice, an accent, a speaking 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. The model follows plain-language direction — slower, closer to the microphone, amused, tired — and performs cues in square brackets such as [sighs] instead of reading them out. SpicyAPI applies no content filter: 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 | About 655 seconds (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 [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. Defaults to neutral. |
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.00045 / 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 with the same notes sounds consistent across chapters.
Character and companion voices
Give a chat character a voice of its own. A whispered style and a short delivery note turn plain text into lines that sound spoken to one listener rather than announced.
Uncensored audio stories
Scripts are read as written, with no content filter. In our tests the model spoke every word of first-person lines and narrated scenes alike, without skipping words or ending the clip early.
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 and, if needed, a style and accent
voice_iddefaults to Kore and accent to neutral. Add style only when you want a specific manner, such as whisper.Direct the reading in instructions
One or two sentences on pace, mood and who is listening work better than a list of adjectives. The note is 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
stylesets an overall manner:whisper,empathetic,vocal_smile,newscaster,promo_hypeordeadpan. Leave it out and the voice reads in its own default manner.accentpicks an English accent and defaults toneutral.pacesets the rhythm:natural,rapid_fire,the_driftorstaccato.instructionstakes free text about how to read: pace, mood, distance from the microphone, who is being addressed.scenesays where and to whom the words are spoken. Neither is spoken.temperature(0–2) sets how much the delivery varies between takes.- Inside
text, cues in square brackets such as[sighs]or[whispering]are acted out rather than read aloud.
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 23–29 seconds of audio in our tests, depending on voice and style. The model stops at 16,384 audio tokens, about 655 seconds. 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 — the longest clip the model can produce — 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 scripts that other services refuse were read word for word, with nothing skipped and no clip ended early.
SpicyAPI adds no content filter: scripts are read as written, whatever they contain. 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-2.5-pro-tts/text-to-speech",
"input": {
"text": "Welcome back. Your files finished rendering a minute ago and are ready to download.",
"accent": "neutral",
"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.







