VITALIFY.ASIA logo

Upgrading Gemini TTS from 3.1 to 3.8: What to Watch Out For

Gemini TTS 3.8 changes how style instructions, audio output, and voice selection work. This article explains the issues we encountered when migrating from 3.1, including instructions being read aloud and WAV header noise, and shows a practical workflow for more stable TTS production.

Nihei TomotakaNihei Tomotaka
Upgrading Gemini TTS from 3.1 to 3.8: What to Watch Out For
On this page

When we upgraded our Gemini text-to-speech (TTS) model from the 3.1 series to the 3.8 series, the model started reading our style instructions out loud. The audio became much longer than before, and some clips even repeated the same sentence.

This article explains the difference we ran into while developing audio content, and what caused it. We also cover how to choose a voice now that 3.8 offers far more of them, and how we build TTS audio content in separate stages.

The content is based on the official Gemini API documentation as of November 16, 2026, and on what we verified in our own development.

Where the instructions go: 3.1 vs. 3.8

With the 3.1 TTS model (gemini-3.1-flash-tts-preview), we sent the style instructions and the script line together in a single text. For example:

[Instructions]
Speak in a calm tone, slowly and carefully.
Leave a short pause between sentences.

[Script]
This is one of the water lily series the painter created late in life.

With 3.1, the model followed the instructions and read only the script line. When we sent the same format to the 3.8 models (gemini-3.8-flash-tts / gemini-3.8-flash-lite-tts), they read the [Instructions] part aloud as well.

The official documentation states that 3.8 treats the text as the exact transcript to be spoken.

Gemini 3.8 TTS treats the text field strictly as a verbatim transcript.

— Text-to-speech generation (TTS)

In 3.8, style instructions go into the style field of speech_metadata. The text contains only the line to be spoken.

{
  "parts": [{
    "text": "This is one of the water lily series the painter created late in life.",
    "speech_metadata": { "style": "calm tone, slow and careful" }
  }]
}

Google AI Studio also has separate fields for the line and for "Style".

The TTS screen in AI Studio. The Style field is separate from the text field

The official migration guide lists five things to review when upgrading from 3.1 to 3.8.

ChangeDetails
Separate style from transcriptMove style instructions to speech_metadata.style; keep the text to the transcript and vocal tags only
Design personas with Voice designReplace long persona descriptions with a voice ID created in Voice design
Send dialogue turn by turnSend one item per speaker turn instead of writing "Speaker: line" in one text
Use angle brackets for vocal tagsUse <laugh>, <sigh>, <short pause>, etc.; avoid sound-effect tags
New default audio format3.1 returned headerless PCM; 3.8 returns WAV with a header

We ran into both the first and the fifth.

The returned audio format

In 3.8, the format of the returned audio also changes. The fifth change caused noise in our audio.

3.1 returned raw audio data (PCM) without a header. 3.8 returns a WAV file with a header at the beginning.

If you treat the whole response as audio data, as you could with 3.1, the header is played back as sound too. In our case, a click appeared at the start of each clip and noise at the end.

There are two fixes. Either extract only the audio data (the data chunk) from the WAV, or request audio/l16 (headerless PCM) as the response format. The Limitations section of the official documentation also says to strip the header before concatenating clips generated line by line.

After we adapted our pipeline to 3.8, both the instruction read-aloud and the noise disappeared.

Choosing a voice

Where the instructions go is not the only change in 3.8. The number of available voices has grown substantially.

With 3.1, you basically chose from 30 voices. With 3.8, in addition to those 30, hundreds of voices are available in what is called the Extended Voice Library. The search box in AI Studio shows "Search 2,000+ voices".

Speaker settings in AI Studio, with voice search and Language, Gender, Pitch, Style and Use case filters

With this many voices, listening to them one by one is not realistic. Speaker settings in AI Studio lets you filter by language, gender, pitch, style and use case.

For calm content such as artwork commentary, we recommend combining two filters: Gender and Pitch. Setting Pitch to Low alone already narrows the list considerably.

Voices filtered by Pitch = Low. Each name shows the voice's character and pitch

Adding Gender = Feminine narrowed it down to just two candidates. At that point, you can listen to all of them in a few minutes. Descriptions such as "Warm and approachable" or "Cool and confident" are also good hints.

Voices filtered by Gender = Feminine and Pitch = Low. Two candidates remain

When producing Japanese narration, it is easier not to filter by Language = Japanese. If you filter by Japanese and then add gender or pitch, almost nothing is left. With a free API key, the combination of Japanese and Low returned zero voices. Voices that are not registered for Japanese still read Japanese reasonably well. Leave the language unspecified, filter by gender and pitch, and compare the candidates by having them read your actual lines.

The same filtering is available through the API. voices.list() (GET /v1beta/voices) accepts filters such as language_code, gender, pitch and contexts. A quick workflow is to shortlist voices in AI Studio and then confirm the voice IDs for production through the API.

Adjusting the mood with style instructions

After choosing a voice, you can fine-tune the delivery with a style instruction. The Style field in AI Studio offers examples such as "Whisper", "Friendly", "Narration" and "Podcast". You can also write freely, for example "calm, low tone, slow and careful".

However, the official Prompting guide advises against long instructions.

Long-form "Audio Profile" paragraphs and multi-bullet "Director's Notes" carried over from earlier models are the most common cause of voice drift.

— Text-to-speech generation (TTS) / Prompting guide

The guide recommends the following.

  • Generate with an empty style first. Most requests need no instruction at all
  • Add a short instruction only to lines that need adjustment (e.g. "casual, friendly")
  • To keep a consistent delivery, reuse the same short instruction for every line
  • Do not try to change inherent traits such as age, gender or accent with style. Change them by choosing a different voice or with Voice design
  • Do not add reminders such as "keep the same voice". More instructions cause more drift

If you built your voice with long instructions in 3.1, it is more stable to shorten them when moving to 3.8 and adjust by choosing a different voice.

Building audio in stages

Finally, here is how we build TTS audio content. Rather than turning a whole document into audio at once, we split the work into the following stages.

StageWhat it doesWhat we use
1. Script generationCreate the sequence of speakers and lines from source material (interview notes, Q&A, etc.)Text generation model (Gemini 3.8 Flash), with JSON output specified
2. Script post-processingAdd readings to words that are easy to misreadDictionary and replacement
3. Audio generationSend each line to TTS one at a timeTTS model (Gemini 3.8 Flash-Lite TTS)
4. Audio assemblyAdjust speed, insert silence between lines, normalize volume and joinAudio processing

There are two reasons for splitting into stages.

First, generating long text as audio in one go tends to lower quality. In a long single generation, the tone may shift midway, or words may be skipped or repeated. With one request per line, you can regenerate only the lines that went wrong. The official guide also recommends splitting long responses into shorter turns rather than forcing them with stronger instructions.

Split long agent responses into shorter turns rather than reaching for stronger style prompts.

— Text-to-speech generation (TTS) / Prompting guide

Second, it makes problems easier to isolate. Whether the script content, the pronunciation or the voice quality is wrong determines which stage to fix. If you keep the intermediate files for each stage (the script JSON and the audio for each line), you can later check where things broke. We found the instruction read-aloud issue this time by comparing the length of each line's audio.

Note that with up to two speakers using prebuilt voices from AI Studio, you can also generate a whole conversation in a single request. To combine custom voices created with Voice design or similar, you need to generate each speaker separately (see Limitations in the official documentation).

Summary

When upgrading Gemini TTS from 3.1 to 3.8, check the following.

Checklist

・Move style instructions to speech_metadata.style and put only the spoken line in the text
・The returned audio is WAV with a header. Strip it before joining, or request audio/l16
・There are over 2,000 voices. In AI Studio, leave the language unspecified, combine gender and pitch filters, then compare
・Keep instructions short. Try without any first, and add them only to lines that need them
・Separate script generation from audio generation, and generate audio one line at a time

Upgrading a model version can change results even for the same request. Read the official Migration guide before migrating, and set up automatic checks on audio length and on the start and end of each clip so you can notice differences early.

At Vitalify Asia, we develop audio content using speech synthesis and products that embed generative AI. We have experience with the kind of model migration and voice and script tuning described in this article. If you have any challenges with speech synthesis or generative AI, feel free to contact us here.

Since 2008, VFA has been involved in more than 1,000 development projects. We also have many projects that are not publicly listed, so please feel free to ask us for details.

Vitalify Asia's development portfolio


Each service's specifications are updated continuously. This article reflects information as of November 16, 2026.

Vitalify Asia Co., Ltd. https://vitalify.asia/

Struggling to turn ideas into reality? With a proven track record of over 1,000 clients, our agile and flexible team will accelerate your business growth.

Back to Blog
I'm Duper, ask me anything!