Gemini 3.1 Flash TTS Text to Speech API

google/gemini-3.1-flash/text-to-speech

Gemini 3.1 Flash TTS Text to Speech turns scripts into multilingual audio with two speakers and 30 preset voices. Direct the overall delivery through style instructions, then use inline tags to shape pauses and emotion within individual lines.

Input

TextRequired257 / 50,000

Style InstructionsOptional

Speech mode

Speakers

Speaker Id

Voice

Speaker Id

Voice

Language CodeOptional

TemperatureOptional

Output FormatOptional

Output

Audio available

$0.120 / 1K chars | 24 credits / 1K chars | Text + Style Instructions

Explore more audio models

ElevenLabs V3 Text to Speech ElevenLabs Music Text to Music

Examples

A little warmth in the rain

A little warmth in the rain — A Mandarin photography tour uses gentle emphasis and unhurried pauses.

Half a wheel

Half a wheel — British race commentary builds pace and excitement, then settles after the finish.

REST API

Quick Start

This flow submits one valid Gemini 3.1 Flash TTS Text to Speech API request, captures its task_id, and reads audio URLs after the asynchronous task ends.

Connect to the Vidgo API

Create an API key, keep it on the server, and send it as Authorization: Bearer VIDGO_API_KEY.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit one speech task

Send the current model ID and text to the unified submit endpoint. The example includes dialogue, speaker voices and delivery instructions.

Submit request

curl --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "google/gemini-3.1-flash/text-to-speech",
  "input": {
    "text": "Actor: [whispers] You're early. The curtain isn't up yet.\nDirector: Same words again. This time, you've been waiting years to see them.\nActor: [excitement] You're early! The curtain isn't up yet!\nDirector: [laughs] There it is. Keep that smile. We're ready.",
    "style_instructions": "An intimate theatre rehearsal. Actor shifts from a secretive whisper to delighted recognition. Director is calm, warm and lightly amused. Keep both voices distinct; do not read speaker labels or tags aloud.",
    "speakers": [
      {
        "speaker_id": "Actor",
        "voice": "Puck"
      },
      {
        "speaker_id": "Director",
        "voice": "Kore"
      }
    ],
    "language_code": "English (US)",
    "temperature": 1,
    "output_format": "mp3"
  }
}'

Wait for the speech result

Read data.task_id and poll only while status is not_started or running. Stop on both finished and failed.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll every 2–5 seconds and back off on 429/5xx. Or provide top-level callback_url to receive a terminal-state callback.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "task-example",
    "status": "running",
    "created_time": "2026-09-25T11:31:42"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "L4VDZ98GS8E3H9RN",
    "status": "finished",
    "files": [
      {
        "file_url": "https://cdn.vidgo.ai/apis/models/google/gemini-3.1-flash/text-to-speech/v1/01/output.mp3",
        "file_type": "audio"
      }
    ],
    "created_time": "2026-09-27T16:24:23",
    "error_message": null,
    "progress": 100
  }
}

Complete runnable polling example

Expand for JavaScript and Python examples that submit the same text request and poll until finished or failed.

Complete runnable polling example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "google/gemini-3.1-flash/text-to-speech",
  "input": {
    "text": "Actor: [whispers] You're early. The curtain isn't up yet.\nDirector: Same words again. This time, you've been waiting years to see them.\nActor: [excitement] You're early! The curtain isn't up yet!\nDirector: [laughs] There it is. Keep that smile. We're ready.",
    "style_instructions": "An intimate theatre rehearsal. Actor shifts from a secretive whisper to delighted recognition. Director is calm, warm and lightly amused. Keep both voices distinct; do not read speaker labels or tags aloud.",
    "speakers": [
      {
        "speaker_id": "Actor",
        "voice": "Puck"
      },
      {
        "speaker_id": "Director",
        "voice": "Kore"
      }
    ],
    "language_code": "English (US)",
    "temperature": 1,
    "output_format": "mp3"
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

while true; do
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep 2
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request Parameters

This table lists only public fields inside input. See Quick Start for top-level model and optional callback_url usage.

Field	Type	Required	Default	Description
input.text	string	Yes	-	Enter 1–50,000 Unicode characters, including spaces, line breaks and audio tags. Prefix dialogue lines with the matching Speaker Id and a colon.
input.style_instructions	string	Optional	-	Describe the tone, pace, accent and emotion for the whole request.
input.voice	string	Optional	Kore	Choose one of 30 voice presets for single-speaker speech. Default: Kore. Achernar, Achird, Algenib, Algieba, Alnilam, Aoede, Autonoe, Callirrhoe, Charon, Despina, Enceladus, Erinome, Fenrir, Gacrux, Iapetus, Kore, Laomedeia, Leda, Orus, Pulcherrima, Puck, Rasalgethi, Sadachbia, Sadaltager, Schedar, Sulafat, Umbriel, Vindemiatrix, Zephyr, Zubenelgenubi.
input.speakers	array	Optional	-	Give each of the two speakers a unique Speaker Id and a Voice, then match each line prefix to the corresponding alias.
input.language_code	string	Optional	-	Choose a language value, or use automatic detection from Text. Arabic (Egypt), Bangla (Bangladesh), Dutch (Netherlands), English (India), English (US), French (France), German (Germany), Hindi (India), Indonesian (Indonesia), Italian (Italy), Japanese (Japan), Korean (South Korea), Marathi (India), Polish (Poland), Portuguese (Brazil), Romanian (Romania), Russian (Russia), Spanish (Spain), Tamil (India), Telugu (India), Thai (Thailand), Turkish (Turkey), Ukrainian (Ukraine), Vietnamese (Vietnam), Afrikaans (South Africa), Albanian (Albania), Amharic (Ethiopia), Arabic (World), Armenian (Armenia), Azerbaijani (Azerbaijan), Basque (Spain), Belarusian (Belarus), Bulgarian (Bulgaria), Burmese (Myanmar), Catalan (Spain), Cebuano (Philippines), Chinese Mandarin (China), Chinese Mandarin (Taiwan), Croatian (Croatia), Czech (Czech Republic), Danish (Denmark), English (Australia), English (UK), Estonian (Estonia), Filipino (Philippines), Finnish (Finland), French (Canada), Galician (Spain), Georgian (Georgia), Greek (Greece), Gujarati (India), Haitian Creole (Haiti), Hebrew (Israel), Hungarian (Hungary), Icelandic (Iceland), Javanese (Java), Kannada (India), Konkani (India), Lao (Laos), Latin (Vatican City), Latvian (Latvia), Lithuanian (Lithuania), Luxembourgish (Luxembourg), Macedonian (North Macedonia), Maithili (India), Malagasy (Madagascar), Malay (Malaysia), Malayalam (India), Mongolian (Mongolia), Nepali (Nepal), Norwegian Bokmal (Norway), Norwegian Nynorsk (Norway), Odia (India), Pashto (Afghanistan), Persian (Iran), Portuguese (Portugal), Punjabi (India), Serbian (Serbia), Sindhi (India), Sinhala (Sri Lanka), Slovak (Slovakia), Slovenian (Slovenia), Spanish (Latin America), Spanish (Mexico), Swahili (Kenya), Swedish (Sweden), Urdu (Pakistan).
input.temperature	number	Optional	1	Set speech variation from 0 to 2. Higher values allow more varied delivery. Default: 1.
input.output_format	string	Optional	mp3	Choose mp3 for playback, wav for uncompressed editing, or ogg_opus for compact audio. Default: mp3. mp3, wav, ogg_opus.
input.speakers[].speaker_id	string	Required per item	-	Use a unique alias made of letters, digits and underscores, then prefix the corresponding lines in Text with that alias.
input.speakers[].voice	string	Required per item	-	Select this speaker’s voice from the 30 presets. Achernar, Achird, Algenib, Algieba, Alnilam, Aoede, Autonoe, Callirrhoe, Charon, Despina, Enceladus, Erinome, Fenrir, Gacrux, Iapetus, Kore, Laomedeia, Leda, Orus, Pulcherrima, Puck, Rasalgethi, Sadachbia, Sadaltager, Schedar, Sulafat, Umbriel, Vindemiatrix, Zephyr, Zubenelgenubi.

Response Fields

The submit response identifies the task. The status response supplies audio files or failure details at a terminal state.

Field	Type	Description
code	integer	Business response code; 0 or 200 indicates success.
message	string	Optional human-readable response message.
data.task_id	string	Unique task ID used for status queries after submission.
data.status	string	not_started, running, finished, or failed.
data.created_time	string	Task creation timestamp.
data.progress	integer	Progress from 0–100 in status responses.
data.files[]	array	Generated files in returned order when finished.
data.files[].file_url	string	Direct generated-audio URL.
data.files[].file_type	string	Speech files are identified as audio.
data.files[].metadata	object	Optional additional information about the generated file, as supplied in the task response.
data.error_message	string \| null	Readable failure reason for failed tasks.

Task Lifecycle

Only the first two states may be polled again. finished and failed are terminal.

not_started
Accepted and queued; wait before checking again.
running
Speech generation is in progress; continue polling.
finished
Successful terminal state; validate files and read audio URLs.
failed
Failure terminal state; read error_message and stop.

Polling and Errors

Authentication401 indicates an authentication failure. Use a valid API key and send requests from your server.
ValidationFollow the request table for the model ID, field types, enums, text length, and numeric ranges.
Polling intervalStart at 2–5 seconds, use exponential backoff for 429/5xx, and enforce an overall timeout.
Terminal statesStop after finished or failed. Treat finished without a valid audio file as a separate error.
Callback optionProvide a public top-level callback_url to receive a flat task object after finished or failed.
Network errorsDistinguish request timeout, network failure, and task failure. Retry the same query only when safe.

Model Specifications

Specification	Value	Details
Model	google/gemini-3.1-flash/text-to-speech	Text-to-speech generation.
text	1–50,000	Unicode characters, including spaces and line breaks.

View the Gemini 3.1 Flash TTS Text to Speech API docs

Gemini 3.1 Flash TTS Text to Speech

Gemini 3.1 Flash TTS Text to Speech is Google’s speech generation model for narration and dialogue. It combines overall style instructions, inline audio tags and individual speaker voices to guide tone, pacing and expression. Assign distinct voices to a podcast host and guest, or turn localized lesson scripts into spoken audio for review and editing.

Why Choose Gemini 3.1 Flash TTS

Generate a two-speaker conversationAssign separate voices to a host and guest, then label their lines to generate the conversation in one request, reducing separate generation and assembly steps.
Direct overall delivery in natural languageDescribe the speaker’s role, tone, accent and pace to set the overall delivery for lessons, stories or product narration.
Shape expression within individual linesMark pauses, whispers or laughter at specific points to direct key lines, emotional turns and character reactions, then review and refine each passage.
Cast roles with 30 preset voicesCompare presets such as Kore, Puck and Zephyr using the same script, then choose a narrator’s voice or pair distinct voices for two dialogue roles.
Voice localized scriptsUse automatic language detection or an explicit language selection to turn translated lesson and product scripts into speech, with style instructions guiding delivery for each version.

Parameters

Parameter	Required	What it controls
text	Required	Enter 1–50,000 Unicode characters, including spaces, line breaks and audio tags. Prefix dialogue lines with the matching Speaker Id and a colon.
style_instructions	Optional	Describe the tone, pace, accent and emotion for the whole request.
voice	Optional	Choose one of 30 voice presets for single-speaker speech. Default: Kore. Default`Kore`
speakers	Optional	Give each of the two speakers a unique Speaker Id and a Voice, then match each line prefix to the corresponding alias.
language_code	Optional	Choose a language value, or use automatic detection from Text.
temperature	Optional	Set speech variation from 0 to 2. Higher values allow more varied delivery. Default: 1. Default`1`
output_format	Optional	Choose mp3 for playback, wav for uncompressed editing, or ogg_opus for compact audio. Default: mp3. Default`mp3`
speakers[].speaker_id	Required per speaker	Use a unique alias made of letters, digits and underscores, then prefix the corresponding lines in Text with that alias.
speakers[].voice	Required per speaker	Select this speaker’s voice from the 30 presets.

Create narration or dialogue

Prepare the scriptEnter the spoken words in Text, organize sentences with punctuation and add audio tags at the relevant points.
Assign speaker voicesFor narration, choose Voice. For dialogue, fill in Speakers[0].Speaker Id and Speakers[1].Speaker Id, select each speaker’s Voice and prefix their lines with the matching alias and a colon.
Set delivery and submitDescribe tone and pace in Style Instructions, choose Language Code and Output Format, review the estimate and select Run.
Listen and exportListen to the voices and pauses in the output panel, then save the audio from the download menu. Revise the script or style instructions for another take.

Usage and pricing

Speech costs $0.120 (24 credits) per 1,000 Unicode characters, calculated from Text plus Style Instructions.

Usage	Rate	Calculation
Speech generation	$0.120 / 1K chars	1,000 total characters cost 24 credits. 500 total characters cost 12 credits ($0.060).
Character count	Text + Style Instructions	Count Unicode code points, including spaces, line breaks and audio tags. A single emoji such as 😀 counts as one code point.

Speech for your project

Podcast dialogueGive host and guest lines separate voices for interview segments and question-and-answer shows.
Product narrationExplain product features at a clear pace and mark pauses before key points for editing alongside demonstrations.
Multilingual lessonsTurn localized lesson scripts into speech using the chosen voice and style instructions across a course.

Direct your speech

Use Style Instructions for the speaker’s role, tone and pace, such as “Warm course instructor, steady pace, pauses around key terms.”
Place [short pause], [whispering] or [laughing] at the relevant point in a line and review a short sample first.
Keep dialogue aliases unique and match each line prefix exactly to the corresponding Speaker Id.
Compare voices using the same short script, then use the selected voice and style instructions for the full piece.

Prepare dialogue lines

Use distinct aliases for the two speakers and prefix each line with its alias and a colon, such as Host: or Guest:.
Put overall delivery directions in Style Instructions and use audio tags in Text for local pauses and emotional changes.

Explore more audio models

ElevenLabs V3 Text to SpeechExplore expressive speech generation.

ElevenLabs Music Text to MusicCreate a music track from a written brief.

Gemini 3.1 Flash TTS Text to Speech API frequently asked questions

What is the Gemini 3.1 Flash TTS Text to Speech API?

Gemini 3.1 Flash TTS Text to Speech is a Google model that turns scripts into narration and dialogue. It offers 30 preset voices, two-speaker dialogue and multilingual delivery for podcasts, lessons and product voiceovers. Style instructions guide the overall delivery, inline tags shape individual lines, and speaker settings assign each role a voice. You can call it programmatically or try it in the Playground tab.

How does Gemini 3.1 Flash TTS generate two-speaker dialogue?

Assign each of the two speakers a voice and a unique alias, then prefix each line with the matching alias and a colon. Dialogue uses the voices configured in Speakers. Aliases consist of letters, digits and underscores.

Which preset voices does Gemini 3.1 Flash TTS offer?

Choose from 30 preset voices, including Kore, Puck and Zephyr. Kore is the default for single-speaker speech. Compare voices with the same short script before selecting one for narration or a dialogue role.

How do I direct overall style in Gemini 3.1 Flash TTS?

Describe tone, pace, accent and emotion in Style Instructions, such as warm instruction or steady narration. Keep the spoken words in Text so you can adjust the script and its delivery separately.

How do inline audio tags work in Gemini 3.1 Flash TTS?

Insert [short pause], [whispering] or [laughing] at the relevant point to guide a pause, whisper or laugh. Review a tagged short passage before applying that delivery to the full script.

How do I create Chinese speech with Gemini 3.1 Flash TTS?

Enter a Chinese script and select Chinese Mandarin (China) or Chinese Mandarin (Taiwan) in Language Code. You can also use automatic detection from the text and describe the desired pacing in Style Instructions.

How long can a Gemini 3.1 Flash TTS script be?

Text accepts 1–50,000 Unicode characters, including spaces, line breaks and audio tags. Organize longer work into chapters and review the voice and pacing on a short passage before generating a full chapter.

Which audio formats does Gemini 3.1 Flash TTS offer?

Output Format offers mp3, wav and ogg_opus, with mp3 as the default. Use MP3 for everyday playback, WAV for editing and Ogg Opus for workflows that favor compact audio files.