O Gemini 3.8 Flash já está disponível. Faça um teste.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Geração de conversão de texto em voz (TTS)

A API Gemini pode transformar entradas de texto em áudio de um ou vários locutores usando os recursos de geração de conversão de texto em voz (TTS) do Gemini. A geração de texto em voz é controlável. Isso significa que você pode combinar metadados estruturados de turnos (speech_metadata) e tags vocais inline para orientar o estilo, o sotaque, o ritmo e o tom do áudio.

A capacidade de TTS é diferente da geração de fala fornecida pela API Live, que foi projetada para áudio interativo e não estruturado, além de entradas e saídas multimodais. Enquanto a API Live se destaca em contextos de conversação dinâmica, a TTS pela API Gemini é feita para cenários que exigem recitação exata de texto com controle refinado sobre estilo e som, como geração de podcasts ou audiolivros.

Este guia mostra como gerar áudio de uma ou várias pessoas usando texto com o Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) e o Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts).

Antes de começar

Use um modelo Gemini TTS listado na seção Modelos compatíveis. Para ter os melhores resultados, consulte Quando usar cada modelo e escolha o melhor para sua carga de trabalho.

Talvez seja útil testar os modelos do Gemini TTS no AI Studio antes de começar a criar.

TTS de um único locutor

Para converter texto em áudio de um único locutor com os modelos Gemini 3.8 TTS, transmita a transcrição literal em input, anexe a estilização no nível da vez usando uma anotação speech_metadata e configure sua voz em generation_config.speech_config. Você pode escolher uma voz nas Opções de voz predefinidas, na Biblioteca de voz estendida (GET /v1beta/voices), em um ID de design de voz personalizado (voice_...) ou em um ID de replicação de voz (voice_... ou voicekey_... sem estado opcional).

Este exemplo salva o áudio WAV padrão (audio/wav) do modelo diretamente em um arquivo:

Python

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))

JavaScript

import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
   });

   const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
   fs.writeFileSync('out.wav', audioBuffer);
}
await main();

Go

package main

import (
    "context"
    "encoding/base64"
    "encoding/binary"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func saveWaveFile(filename string, pcmData []byte) error {
    f, err := os.Create(filename)
    if err != nil {
        return err
    }
    defer f.Close()

    sampleRate := uint32(24000)
    numChannels := uint16(1)
    bitsPerSample := uint16(16)
    byteRate := sampleRate * uint32(numChannels) * uint32(bitsPerSample/8)
    blockAlign := numChannels * (bitsPerSample / 8)
    dataSize := uint32(len(pcmData))

    f.WriteString("RIFF")
    binary.Write(f, binary.LittleEndian, uint32(36+dataSize))
    f.WriteString("WAVEfmt ")
    binary.Write(f, binary.LittleEndian, uint32(16))
    binary.Write(f, binary.LittleEndian, uint16(1))
    binary.Write(f, binary.LittleEndian, numChannels)
    binary.Write(f, binary.LittleEndian, sampleRate)
    binary.Write(f, binary.LittleEndian, byteRate)
    binary.Write(f, binary.LittleEndian, blockAlign)
    binary.Write(f, binary.LittleEndian, bitsPerSample)
    f.WriteString("data")
    binary.Write(f, binary.LittleEndian, dataSize)
    _, err = f.Write(pcmData)
    return err
}

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    generationConfig := &interactions.GenerationConfig{
        SpeechConfig: genai.Ptr(interactions.NewSpeechConfigUnion([]interactions.SpeechConfig{
            {Voice: genai.Ptr("Kore")},
        })),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.1-flash-tts-preview"),
            Input: interactions.NewInteractionsInput("Say cheerfully: Have a wonderful day!"),
            ResponseFormat: genai.Ptr(interactions.NewCreateModelInteractionResponseFormat(
                interactions.NewResponseFormat(interactions.AudioResponseFormat{}),
            )),
            GenerationConfig: generationConfig,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputAudio != nil && res.Interaction.OutputAudio.Data != nil {
        pcmBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputAudio.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := saveWaveFile("out.wav", pcmBytes); err != nil {
            log.Fatal(err)
        }
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }'

É possível recuperar os dados de áudio gerados usando a propriedade interaction.output_audio, que retorna o último bloco de áudio gerado. Para mais detalhes sobre propriedades de conveniência, consulte a Visão geral das interações.

TTS com vários falantes

Para diálogos com vários falantes, configure dois falantes em speech_config.speakers e transmita cada turno como um item de texto separado com uma anotação speech_metadata especificando o speaker e o style opcional no nível do turno. Use "mode": "conversational" para uma cadência natural de troca de turnos:

Python

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [
            {
                "type": "text",
                "text": "How's it going today Jane?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Joe",
                    "style": "cheerful and friendly",
                }],
            },
            {
                "type": "text",
                "text": "Not too bad, how about you? Ready to test these new voices?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Jane",
                    "style": "calm and relaxed",
                }],
            },
        ],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": {
            "mode": "conversational",
            "speakers": [
                {"speaker": "Joe", "voice": "Puck"},
                {"speaker": "Jane", "voice": "Kore"},
            ],
        }
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))

JavaScript

import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [
            {
               type: 'text',
               text: "How's it going today Jane?",
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Joe',
                  style: 'cheerful and friendly',
               }],
            },
            {
               type: 'text',
               text: 'Not too bad, how about you? Ready to test these new voices?',
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Jane',
                  style: 'calm and relaxed',
               }],
            },
         ],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: {
            mode: 'conversational',
            speakers: [
               { speaker: 'Joe', voice: 'Puck' },
               { speaker: 'Jane', voice: 'Kore' },
            ],
         },
      },
   });

   const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
   fs.writeFileSync('out.wav', audioBuffer);
}

await main();

Go

package main

import (
    "context"
    "encoding/base64"
    "encoding/binary"
    "log"
    "os"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func saveWaveFile(filename string, pcmData []byte) error {
    f, err := os.Create(filename)
    if err != nil {
        return err
    }
    defer f.Close()

    sampleRate := uint32(24000)
    numChannels := uint16(1)
    bitsPerSample := uint16(16)
    byteRate := sampleRate * uint32(numChannels) * uint32(bitsPerSample/8)
    blockAlign := numChannels * (bitsPerSample / 8)
    dataSize := uint32(len(pcmData))

    f.WriteString("RIFF")
    binary.Write(f, binary.LittleEndian, uint32(36+dataSize))
    f.WriteString("WAVEfmt ")
    binary.Write(f, binary.LittleEndian, uint32(16))
    binary.Write(f, binary.LittleEndian, uint16(1))
    binary.Write(f, binary.LittleEndian, numChannels)
    binary.Write(f, binary.LittleEndian, sampleRate)
    binary.Write(f, binary.LittleEndian, byteRate)
    binary.Write(f, binary.LittleEndian, blockAlign)
    binary.Write(f, binary.LittleEndian, bitsPerSample)
    f.WriteString("data")
    binary.Write(f, binary.LittleEndian, dataSize)
    _, err = f.Write(pcmData)
    return err
}

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    prompt := "TTS the following conversation between Joe and Jane:\n" +
        "Joe: How's it going today Jane?\n" +
        "Jane: Not too bad, how about you?"

    generationConfig := &interactions.GenerationConfig{
        SpeechConfig: genai.Ptr(interactions.NewSpeechConfigUnion([]interactions.SpeechConfig{
            {Speaker: genai.Ptr("Joe"), Voice: genai.Ptr("Kore")},
            {Speaker: genai.Ptr("Jane"), Voice: genai.Ptr("Puck")},
        })),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.1-flash-tts-preview"),
            Input: interactions.NewInteractionsInput(prompt),
            ResponseFormat: genai.Ptr(interactions.NewCreateModelInteractionResponseFormat(
                interactions.NewResponseFormat(interactions.AudioResponseFormat{}),
            )),
            GenerationConfig: generationConfig,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    if res.Interaction.OutputAudio != nil && res.Interaction.OutputAudio.Data != nil {
        pcmBytes, err := base64.StdEncoding.DecodeString(*res.Interaction.OutputAudio.Data)
        if err != nil {
            log.Fatal(err)
        }
        if err := saveWaveFile("out.wav", pcmBytes); err != nil {
            log.Fatal(err)
        }
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "How'\''s it going today Jane?",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Joe",
            "style": "cheerful and friendly"
          }]
        },
        {
          "type": "text",
          "text": "Not too bad, how about you? Ready to test these new voices?",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Jane",
            "style": "calm and relaxed"
          }]
        }
      ]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": {
        "mode": "conversational",
        "speakers": [
          { "speaker": "Joe", "voice": "Puck" },
          { "speaker": "Jane", "voice": "Kore" }
        ]
      }
    }
  }'

Controlar o estilo de fala com metadados e tags

O Gemini 3.8 TTS trata o campo text estritamente como uma transcrição literal. Para controlar a entrega sem que as rubricas sejam lidas em voz alta, divida as instruções por escopo:

Entrega sustentada no nível da vez (speech_metadata.style): coloque emoções, estilo de entrega, prosódia, ritmo e volume que se aplicam a uma vez inteira no campo style (por exemplo, "style": "whispered urgently", "style": "out of breath" ou "style": "warm and enthusiastic").
Eventos pontuais (tags inline): coloque pausas ou explosões vocais momentâneas não relacionadas à fala diretamente na transcrição usando colchetes angulares (por exemplo, "Wait... <short pause> did you hear that? <sigh>" ou "Excuse me <cough> as I was saying...").

Consulte o guia de comandos para conferir as práticas recomendadas abrangentes.

Go

package main

import (
    "context"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    transcriptRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput(
                "Generate a short transcript around 100 words that reads " +
                    "like it was clipped from a podcast by excited herpetologists. " +
                    "The hosts names are Dr. Anya and Liam.",
            ),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    var transcript string
    if transcriptRes.Interaction.OutputText != nil {
        transcript = *transcriptRes.Interaction.OutputText
    }

    generationConfig := &interactions.GenerationConfig{
        SpeechConfig: genai.Ptr(interactions.NewSpeechConfigUnion([]interactions.SpeechConfig{
            {Speaker: genai.Ptr("Dr. Anya"), Voice: genai.Ptr("Kore")},
            {Speaker: genai.Ptr("Liam"), Voice: genai.Ptr("Puck")},
        })),
    }

    ttsRes, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.1-flash-tts-preview"),
            Input: interactions.NewInteractionsInput(transcript),
            ResponseFormat: genai.Ptr(interactions.NewCreateModelInteractionResponseFormat(
                interactions.NewResponseFormat(interactions.AudioResponseFormat{}),
            )),
            GenerationConfig: generationConfig,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    _ = ttsRes
}

Streaming de geração de fala

É possível transmitir o áudio gerado enquanto ele é sintetizado definindo stream: true. Ao contrário das solicitações unárias (que retornam um arquivo WAV completo com um cabeçalho RIFF), as solicitações de streaming retornam blocos brutos de PCM linear de 16 bits com sinalização little-endian (audio/l16, 24 kHz, mono) sem cabeçalho por padrão. Assim, os blocos de áudio podem ser reproduzidos ou concatenados continuamente sem cabeçalhos de contêiner.

Python

import base64
from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
    stream=True,
)

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "audio":
            audio_data = base64.b64decode(event.delta.data)
            # Process the audio chunk (e.g. play it or write to a file)

JavaScript

import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const stream = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
      stream: true,
   });

   for await (const event of stream) {
      if (event.event_type === 'step.delta') {
         if (event.delta.type === 'audio') {
            const audioBuffer = Buffer.from(event.delta.data, 'base64');
            // Process the audio buffer
         }
      }
   }
}
await main();

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    },
    "stream": true
  }'

Formatos de saída de áudio

Os modelos de TTS do Gemini 3.8 usam formatos de áudio padrão diferentes, dependendo se a solicitação é unária ou de streaming:

Solicitações unárias (stream=False): retornam áudio WAV (audio/wav) completo com um cabeçalho RIFF padrão (24 kHz, mono, PCM little-endian de 16 bits com sinal). É possível salvar os bytes de áudio decodificados diretamente em um arquivo .wav sem adicionar manualmente um cabeçalho WAV.
Solicitações de streaming (stream=True): retornam blocos PCM linear bruto sem cabeçalho (audio/l16) (24 kHz, mono, PCM little-endian assinado de 16 bits) por padrão para que os blocos possam ser transmitidos ou concatenados continuamente sem cabeçalhos de contêiner em cada bloco.

Para solicitar uma codificação de áudio ou taxa de amostragem diferente, configure mime_type e sample_rate opcional em response_format:

Formato	Valor de `mime_type`	Descrição
WAV (padrão unário)	`"audio/wav"`	Arquivo WAV sem compactação com um cabeçalho RIFF (PCM de 16 bits assinado little-endian, mono, 24 kHz padrão). Padrão para solicitações unárias.
PCM bruto (L16) (padrão de streaming)	`"audio/l16"`	Áudio PCM linear de 16 bits sem compactação, sem cabeçalho, little endian (24 kHz, mono). Padrão para solicitações de streaming.
Mu-law	`"audio/mulaw"`	Áudio codificado em lei mu G.711 de 8 bits (usado com frequência em sistemas de telefonia/URA da América do Norte e do Japão).
Lei A	`"audio/alaw"`	Áudio codificado de 8 bits G.711 A-law (usados com frequência em sistemas de telefonia europeus e internacionais).

Também é possível especificar sample_rate em Hertz (por exemplo, 24000, 16000 ou 8000).

Python

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={
        "type": "audio",
        "mime_type": "audio/l16",  # "audio/wav" (default), "audio/l16", "audio/mulaw", or "audio/alaw"
        "sample_rate": 24000,
    },
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
)

with open("out.pcm", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))

JavaScript

import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: {
         type: 'audio',
         mime_type: 'audio/l16', // 'audio/wav' (default), 'audio/l16', 'audio/mulaw', or 'audio/alaw'
         sample_rate: 24000,
      },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
   });

   const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
   fs.writeFileSync('out.pcm', audioBuffer);
}
await main();

Go

package main

import (
    "context"
    "encoding/base64"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    generationConfig := &interactions.GenerationConfig{
        SpeechConfig: genai.Ptr(interactions.NewSpeechConfigUnion([]interactions.SpeechConfig{
            {Voice: genai.Ptr("Kore")},
        })),
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.1-flash-tts-preview"),
            Input: interactions.NewInteractionsInput("Say cheerfully: Have a wonderful day!"),
            ResponseFormat: genai.Ptr(interactions.NewCreateModelInteractionResponseFormat(
                interactions.NewResponseFormat(interactions.AudioResponseFormat{}),
            )),
            GenerationConfig: generationConfig,
            Stream:           genai.Ptr(true),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    stream := res.InteractionSSEStreamEvent
    defer stream.Close()

    for stream.Next() {
        event := stream.Value()
        if stepDelta := event.GetDataStepDelta(); stepDelta != nil {
            if audioDelta := stepDelta.GetDeltaAudio(); audioDelta != nil && audioDelta.Data != nil {
                audioData, err := base64.StdEncoding.DecodeString(*audioDelta.Data)
                if err != nil {
                    log.Fatal(err)
                }
                // Process the audio chunk (e.g. play it or write to a file)
                _ = audioData
            }
        }
    }
    if err := stream.Err(); err != nil {
        log.Fatal(err)
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio",
      "mime_type": "audio/l16",
      "sample_rate": 24000
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }'

Opções de voz

O Gemini 3.8 TTS oferece quatro maneiras de selecionar ou criar vozes:

Vozes predefinidas do Studio:30 vozes selecionadas listadas na tabela a seguir.
Biblioteca de vozes estendida:centenas de vozes adicionais em vários idiomas, sotaques e arquétipos de personagens acessíveis usando client.voices.list() (GET /v1beta/voices).
Design de voz:gere uma persona vocal personalizada com base em uma descrição em linguagem natural no Google AI Studio ou usando POST /v1beta/voices (type="prompted", que retorna um ID voice_... persistente e uma prévia em WAV sample_audio em CreateVoice e GetVoice).
Replicação de voz:replique a voz de um falante usando áudio de referência e consentimento no Google AI Studio ou usando POST /v1beta/voices (type="replicated", store=True persistente por padrão ou store=False sem estado opcional).

Limites e TTL de voz personalizados

Tipo de voz	Modo de armazenamento	Cota / limite	Retenção (TTL)
Vozes com estado (`voice_...`, solicitadas ou replicadas)	`store=True`	200 vozes por projeto (compartilhadas entre vozes solicitadas e replicadas)	1 ano
Chaves de voz sem estado (`voicekey_...`, replicadas)	`store=False`	Gerenciada pelo cliente	7 dias

Vozes predefinidas

Zephyr: Brilhante	Puck: Upbeat	Charon: informativa
Kore: firme	Fenrir: Excitável	Leda: Juventude
Orus: Firme	Aoede: Breezy	Callirrhoe -- Tranquila
Autonoe: Bright	Enceladus: Breathy	Iapetus: Clear
Umbriel: tranquilo	Algieba: Suave	Despina: Smooth
Erinome: Limpar	Algenib: Gravelly	Rasalgethi: informativa
Laomedeia: Upbeat	Achernar: Soft	Alnilam: Firm
Schedar: Even	Gacrux: Adulto	Pulcherrima: projetada
Achird: Friendly	Zubenelgenubi: Casual	Vindemiatrix: Gentle
Sadachbia: Lively	Sadaltager: Conhecimento	Sulafat: quente

Biblioteca de vozes e filtragem estendidas

Além das 30 vozes de estúdio apresentadas na tabela anterior, a Biblioteca de vozes estendida oferece centenas de vozes adicionais em vários idiomas, sotaques regionais, personas de personagens e domínios. Você pode navegar, filtrar e testar a biblioteca de vozes completa de forma interativa no Google AI Studio ou consultar programaticamente usando client.voices.list() (GET /v1beta/voices, usando google-genai 2.25.0+ / @google/genai 2.24.0+).

O ListVoices retorna suas vozes personalizadas armazenadas (ordenadas da mais recente para a mais antiga), seguidas pelas vozes pré-criadas do catálogo que correspondem aos seus critérios de filtro. Quando vários valores são transmitidos para um filtro de lista, as vozes que correspondem a qualquer valor nesse filtro são retornadas (OR), enquanto parâmetros de filtro distintos se combinam com AND:

Parâmetro	Tipo	Descrição
`language_code`	`list[str]`	Tags de idioma BCP-47 (por exemplo, `["en-US", "en-GB"]`). Correspondência exata que não diferencia maiúsculas de minúsculas.
`region_code`	`list[str]`	Códigos ISO 3166-1 alfa-2 ou regionais da ONU M.49 (por exemplo, `["US", "GB"]`).
`accent`	`list[str]`	Descritores de sotaque regional (por exemplo, `["American", "British"]`).
`gender`	`list[str]`	Apresentação de gênero percebida (`"female"`, `"male"` ou `"neutral"`).
`pitch`	`list[str]`	Classificação de tom vocal (`"low"`, `"medium"` ou `"high"`).
`persona`	`list[str]`	Personagem vocal ou arquétipo de personagem (por exemplo, `["Warm, Friendly"]`, `["Narrator"]`).
`contexts` (`context` em REST)	`list[str]`	Domínio de uso ideal (por exemplo, `["Audiobook", "Conversational", "News"]`).
`type` (`type_` em Python)	`list[str]`	Filtre por origem da voz: `"prebuilt"`, `"prompted"` (Design de voz) ou `"replicated"` (Replicação de voz).
`search`	`str`	A pesquisa de substring de texto livre foi correspondida sem distinção entre maiúsculas e minúsculas em relação a `display_name` e `description`.
`page_size`	`int`	Número máximo de vozes retornadas por página (padrão `50`, máximo `1000`).
`page_token`	`str`	Token de `response.next_page_token` para buscar a próxima página de resultados.

Python

from google import genai

client = genai.Client()

# Filter the Voice Library by language, gender, pitch, domain context, and keyword
response = client.voices.list(
    language_code=["en-US", "en-GB"],
    gender=["female"],
    pitch=["medium", "low"],
    contexts=["Audiobook", "Conversational"],
    type_=["prebuilt"],
    search="warm",
    page_size=50,
)

for voice in response.voices or []:
    print(
        f"{voice.id} | {voice.display_name} ({voice.language_code},"
        f" {voice.accent}, {voice.gender}, pitch={voice.pitch}):"
        f" {voice.description}"
    )

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI();

// Filter the Voice Library by language, gender, pitch, domain context, and keyword
const response = await ai.voices.list({
  language_code: ["en-US", "en-GB"],
  gender: ["female"],
  pitch: ["medium", "low"],
  contexts: ["Audiobook", "Conversational"],
  type: ["prebuilt"],
  search: "warm",
  page_size: 50,
});

for (const voice of response.voices ?? []) {
  console.log(
    `${voice.id} | ${voice.display_name} (${voice.language_code}, ${voice.accent}, ${voice.gender}, pitch=${voice.pitch}): ${voice.description}`
  );
}

REST

curl -G "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --data-urlencode "language_code=en-US" \
  --data-urlencode "language_code=en-GB" \
  --data-urlencode "gender=female" \
  --data-urlencode "pitch=medium" \
  --data-urlencode "context=Audiobook" \
  --data-urlencode "type=prebuilt" \
  --data-urlencode "search=warm" \
  --data-urlencode "page_size=50"

Idiomas compatíveis

Os modelos de TTS detectam o idioma de entrada automaticamente. O Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) aceita 130 idiomas, e o Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) aceita 101 idiomas:

Idioma	Gemini 3.8 Flash TTS	Gemini 3.8 Flash-Lite TTS
Achém (escrita árabe)	✔️	✔️
Africâner	✔️	✔️
Akan	✔️	✔️
Amárico	✔️	✔️
Armênio	✔️	✔️
Assamês	✔️	✔️
Awadhi	✔️	✔️
Balinês	✔️	✔️
Bengali	✔️	✔️
Banjar (escrita árabe)	✔️	—
Banjar (alfabeto latino)	✔️	✔️
Bashkir	✔️	—
Basco	✔️	✔️
Bielorrusso	✔️	✔️
Bemba	✔️	—
Boiapuri	✔️	✔️
Bósnio	✔️	✔️
Buguinês	✔️	✔️
Búlgaro	✔️	✔️
Birmanês	✔️	—
Cantonês	✔️	✔️
Catalão	✔️	✔️
Cebuano	✔️	✔️
Sorâni	✔️	✔️
Chhattisgarhi	✔️	✔️
Chinês (escrita Hans)	✔️	✔️
Chinês (script Hant)	✔️	✔️
Tártaro da Crimeia	✔️	—
Croata	✔️	✔️
Tcheco	✔️	✔️
Dinamarquês	✔️	✔️
Holandês	✔️	✔️
Diúla	✔️	—
Dzonga	✔️	—
Árabe egípcio	✔️	✔️
Inglês	✔️	✔️
Estoniano	✔️	✔️
Filipino	✔️	✔️
Finlandês	✔️	—
Francês	✔️	✔️
Galego	✔️	✔️
Ganda	✔️	✔️
Georgiano	✔️	✔️
Alemão	✔️	✔️
Grego	✔️	✔️
Guarani	✔️	—
Gujarati	✔️	✔️
Crioulo haitiano	✔️	✔️
Halh mongol	✔️	✔️
Hauçá	✔️	✔️
Hebraico	✔️	✔️
Hindi	✔️	✔️
Húngaro	✔️	✔️
Islandês	✔️	✔️
Igbo	✔️	—
Iloko	✔️	✔️
Indonésio	✔️	✔️
Persa iraniano	✔️	✔️
Italiano	✔️	✔️
Japonês	✔️	✔️
Javanês	✔️	✔️
Kabyle	✔️	—
Kamba	✔️	✔️
Canarês	✔️	✔️
Caxemira (escrita árabe)	✔️	✔️
Caxemira (escrita deva)	✔️	✔️
Cazaque	✔️	✔️
Khmer	✔️	✔️
Kikuyu	✔️	✔️
Quiniaruanda	✔️	✔️
Quicongo	✔️	✔️
Coreano	✔️	✔️
Quirguiz	✔️	✔️
Laosiano	✔️	✔️
Latgaliano	✔️	—
Lingala	✔️	✔️
Lituano	✔️	—
Luxemburguês	✔️	—
Macedônio	✔️	✔️
Magahi	✔️	✔️
Maithili	✔️	✔️
Malaiala	✔️	✔️
Maltês	✔️	✔️
Manipuri	✔️	✔️
Marati	✔️	✔️
Minangkabau (escrita árabe)	✔️	✔️
Minangkabau (alfabeto latino)	✔️	—
Mizo	✔️	✔️
Nepalês (idioma individual)	✔️	✔️
Fulfulde nigeriano	✔️	✔️
Azerbaijano do norte	✔️	✔️
Soto do norte	✔️	✔️
Uzbeque do norte	✔️	✔️
Bokmål norueguês	✔️	✔️
Norueguês (Nynorsk)	✔️	✔️
Nianja	✔️	✔️
Occitânico	✔️	—
Odia (idioma individual)	✔️	✔️
Língua pangasiana	✔️	—
Persa (Afeganistão)	✔️	✔️
Polonês	✔️	✔️
Português	✔️	✔️
Punjabi	✔️	✔️
Romeno	✔️	✔️
Russo	✔️	✔️
Santali	✔️	✔️
Sérvio	✔️	✔️
Sindi	✔️	—
Cingalês	✔️	✔️
Eslovaco	✔️	✔️
Esloveno	✔️	—
Somali	✔️	—
Azerbaijão do Sul	✔️	✔️
Pashto meridional	✔️	✔️
Soto do sul	✔️	—
Espanhol	✔️	✔️
Árabe padrão (escrita árabe)	✔️	✔️
Árabe padrão (alfabeto latino)	✔️	✔️
Letão padrão	✔️	✔️
Malaio padrão	✔️	✔️
Suaíli (idioma individual)	✔️	—
Swati	✔️	—
Sueco	✔️	—
Tadjique	✔️	—
Tâmil	✔️	✔️
Télugo	✔️	✔️
Tailandês	✔️	—
Tigrínia	✔️	—
Albanês Tosk	✔️	—
Uigur	✔️	—

Modelos compatíveis

Modelo	Falante único	Vários falantes	Design de voz	Replicação de voz
Gemini 3.8 Flash TTS (`gemini-3.8-flash-tts`)	✔️	✔️	✔️	✔️
Gemini 3.8 Flash-Lite TTS (`gemini-3.8-flash-lite-tts`)	✔️	✔️	✔️	✔️
Pré-lançamento do Gemini 3.1 Flash TTS	✔️	✔️	—	—
Pré-lançamento da TTS do Gemini 2.5 Pro	✔️	✔️	—	—

Quando usar cada modelo

Os dois modelos de TTS do Gemini 3.8 compartilham o mesmo esquema de API e formato de solicitação, permitindo que você alterne entre eles com uma única mudança de parâmetro:

Use o Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) quando a fidelidade acústica máxima, a atuação sutil e o controle expressivo forem prioridade. Ele é ideal para trabalhos criativos de qualidade profissional, diálogos complexos com vários falantes, tags de explosão vocal pesadas, pronúncias difíceis, dialetos regionais ou minoritários e narrações longas que exigem estabilidade de voz e tom ambiente.
Use o Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) como substituto rápido e econômico para gemini-3.1-flash-tts-preview. Ele é otimizado para produção em massa de alto volume, cascatas de agentes de voz conversacionais, recursos de leitura em voz alta, replicação de voz confiável e fala cotidiana de um único falante nos principais idiomas.

Guia de migração

Se você estiver migrando do gemini-3.1-flash-tts-preview ou de modelos anteriores do Gemini TTS para o Gemini 3.8 TTS:

Mova as instruções de nível de turno para speech_metadata:o Gemini 3.8 TTS trata o texto de entrada estritamente como uma transcrição literal. Mova as instruções de entrega sustentada (style, como "whispering", "out of breath" ou "speaking slowly") e os identificadores de locutor (speaker) para anotações speech_metadata estruturadas em vez de incorporar rubricas no texto da transcrição.
Use tags inline com colchetes angulares apenas para eventos vocais pontuais:mantenha vocalizações e pausas momentâneas não relacionadas à fala inline na transcrição usando colchetes angulares (como <laugh>, <sigh>, <cough>, <breath> ou <short pause>). Evite tags de efeitos sonoros (como aplausos ou ruídos) e coloque estilos de entrega em speech_metadata.style.
Especifique speaker em cada vez em solicitações com vários participantes:cada vez em uma solicitação com vários participantes precisa incluir explicitamente speaker em speech_metadata, correspondendo a um dos participantes configurados.
Crie personas de design com o Voice design:substitua blocos de vários parágrafos "Audio Profile" ou "Director's Notes" por uma voz personalizada criada em Voice design e transmita esse ID voice_... nas solicitações de TTS com strings style mínimas ou vazias.
Considerar a saída WAV padrão (audio/wav) em solicitações unárias:ao contrário do gemini-3.1-flash-tts-preview e de modelos de TTS anteriores (que retornavam PCM bruto sem cabeçalho audio/l16 por padrão), o Gemini 3.8 TTS retorna áudio WAV (audio/wav) com um cabeçalho RIFF padrão por padrão para solicitações unárias.
- Se o código anteriormente encapsulava bytes PCM brutos em um cabeçalho WAV (por exemplo, usando o módulo wave do Python ou ffmpeg), remova o wrapper de cabeçalho manual e grave os bytes retornados diretamente em um arquivo .wav.
- Se o pipeline exigir áudio PCM bruto, mu-law ou A-law sem cabeçalho, defina explicitamente response_format como "audio/l16", "audio/mulaw" ou "audio/alaw". Consulte Formatos de saída de áudio.

Guia para a criação de comandos

Os modelos de TTS do Gemini 3.8 tratam o texto de entrada estritamente como uma transcrição literal. Ao contrário dos modelos de prévia anteriores, em que as rubricas eram incorporadas em texto simples, o TTS do Gemini 3.8 separa as instruções sustentadas no nível da vez (speech_metadata) das tags vocais inline pontuais.

Campo de estilo x tags inline

Divida as instruções de performance por escopo:

Entrega no nível da vez (speech_metadata.style): coloque atributos de entrega sustentada, como emoção, prosódia, ritmo geral ou estilo de entrega (como "whispering", "out of breath", "muttering" ou "sarcastic"), no campo style de speech_metadata. Para criar um personagem e uma performance estáveis em todas as interações, crie a persona antecipadamente em Design de voz e use style apenas para ajustes opcionais no nível da interação.
Eventos pontuais (tags inline): coloque pausas, respirações ou explosões vocais momentâneas não relacionadas à fala inline dentro da transcrição usando colchetes angulares (<cough>, <breath>, <sigh>, <short pause>). Use colchetes angulares (<...>) para ter a melhor qualidade do áudio e prefira vocalizações humanas em vez de efeitos sonoros não vocais.

Escopo	Onde colocar	Exemplos
No nível da conversa (mantido durante toda a conversa)	`speech_metadata.style`	`"angry tone"`, `"speaking rapidly"`, `"out of breath"`, `"whispers"`, `"sarcastic"`
Pontual (ocorre em uma palavra específica)	Em linha em `text` (`<...>`)	`"<cough> Thank you all for coming tonight! <throat-clearing> As I was saying..."`

Ritmo e pausas

É possível controlar o ritmo e o silêncio em três níveis de granularidade:

Pontuação e reticências:use vírgulas, travessões (--) e reticências (...) para hesitação natural na conversa.
Tags de pausa inline:insira <short pause> ou <long pause> nos pontos exatos do script em que um falante deve pausar: text Hold on, let me think... <short pause> Alright, I've got it.
Velocidade no nível da vez:defina "style": "speaking rapidly" ou "style": "speaking slowly" em speech_metadata para controlar a taxa de fala em toda a vez.

Prosódia e tom

Use speech_metadata.style para controlar a prosódia, a entonação e a inflexão em uma fala (por exemplo, "style": "high pitch, cheerful and excited inflection" ou "style": "monotone and flat"). Se a emoção ou a prosódia mudar no meio do diálogo, divida o script em falas separadas com valores style distintos para cada uma.

Ênfase

Use letras maiúsculas em palavras específicas na transcrição, combinadas com pontuação e tags vocais inline, para enfatizar naturalmente as palavras-chave:

This is a VERY important point!
It was a VERY long day <sigh> ... nobody listens anymore.

Explosões vocais e sons não verbais

Coloque vocalizações humanas que não sejam de fala em linha usando colchetes angulares (<...>) no ponto exato em que o som deve ocorrer. As tags vocais recomendadas incluem:

`<argh>`	`<breath>`	`<heavy breath>`	`<exhales>`
`<cackle>`	`<cheer>`	`<chuckle>` / `<chuckles>`	`<cough>`
`<cry>`	`<gasp>`	`<giggle>`	`<groan>`
`<growl>`	`<grunt>`	`<grr>`	`<hiss>`
`<laugh>` / `<laughter>`	`<moan>`	`<pant>`	`<pff>` / `<phew>`
`<scream>`	`<shout>`	`<shriek>`	`<sigh>` / `<sighs>`
`<sneeze>`	`<snicker>`	`<snort>`	`<sob>`
`<throat-clearing>`	`<tsk>`	`<whimper>`	`<whispers>` / `<whispering>`
`<yawn>`	`<short pause>`	`<long pause>`

Backchannels e fala sobreposta

Em diálogos com vários falantes, envolva as reações do listener com caracteres de barra vertical (|reaction|) durante a vez de um falante para criar backchannels naturais ou sobreposição de fala sem interromper com uma vez separada por reação.

Trocas curtas de canal de interação:coloque reações breves do ouvinte (|oh hmm|, |oh really?|, |absolutely|) dentro da vez do falante ativo:
- Turno 1 (interlocutor A): "So the launch is Thursday |oh hmm| Are we actually ready?"
- Turno 2 (Speaker B): "Ready enough |oh really?| The last blocker cleared this morning."
- Turno 3 (pessoa A): "Then let's ship it |absolutely| and watch the dashboards."
Fala sobreposta e intercalada:use vários segmentos de barra vertical para simular fala simultânea ou intercalada entre dois falantes (funciona melhor com gemini-3.8-flash-tts):
- Contagem regressiva/refrão simultâneo:"Let's surprise him on three |ok| ready?" seguido de "one. two. three. |happy| happy |birthday| birthday!"
- Sobreposição total de falas:"Hello |oh| there |my| it |goodness| must |gracious| be |would| almost |you| time |look| for |at that| dinner"

Consistência entre gerações e o que evitar

Siga estas diretrizes para manter a identidade vocal estável em todas as conversas:

Crie personas de design no início do design de voz em vez de blocos de estilo longos:parágrafos longos "Audio Profile" e listas com vários marcadores "Director's Notes" transferidos de modelos anteriores são a causa mais comum de variação de voz. Use essa mesma intuição criativa no Design de voz para gerar uma persona voice_... personalizada persistente e, em seguida, use esse ID de voz nas suas chamadas de TTS.
Confie na referência de voz para estabilidade (omita as metainstruções): os modelos de TTS do Gemini 3.8 são treinados para se ancorar primeiro na referência de áudio. Não inclua instruções para manter a voz constante (como "do not switch speaker identity" ou "maintain identical timbre"). Texto extra no comando aumenta o desvio. Remova instruções de estilo desnecessárias e deixe o modelo variar naturalmente em torno do ponto estável fornecido pela referência de voz.
Não tente mudar características imutáveis do falante em style:evite colocar idade, gênero, nomes ou mudanças permanentes de sotaque em speech_metadata.style. Em vez disso, escolha uma voz regional na Biblioteca de vozes avançada ou crie uma com Design de voz.

Fluxo de trabalho recomendado

Crie o personagem uma vez:crie seu personagem em Design de voz ou selecione uma voz regional na Biblioteca de vozes avançada que corresponda ao idioma e à persona de destino.
Escreva transcrições faladas naturais com disfluências:para ter o máximo de naturalidade, escreva o text como uma transcrição falada real, incluindo disfluências e hesitações naturais da conversa (por exemplo, "Oh uh yeah I think... hm, so that's interesting").
Teste a TTS simples primeiro:sintetize sua transcrição com um campo style vazio. A maioria das solicitações não precisa de nenhuma instrução style.
Adicione comandos curtos de style apenas para ajustes:adicione uma string style concisa (como "casual, friendly" ou "muttering, then reassuring") apenas para rodadas que precisam de um ajuste de entrega específico e reutilize essa mesma string curta em todas as rodadas quando quiser uma base consistente.

Diálogo multiturno e agentes de voz

Ao criar agentes de voz de conversação em tempo real ou aplicativos multiturno:

Faça uma chamada de TTS por vez à medida que os blocos de texto do LLM chegam.
Deixe o voice configurado (pré-criado, voice_... projetado ou voice_... / voicekey_... replicado) transmitir a identidade do falante em todos os turnos. Nunca reenvie uma persona de personagem longa a cada turno.
Deixe o campo style por turno vazio ou envie uma string constante curta (como "casual, friendly") para toda a conversa.
Divida respostas longas do agente em turnos mais curtos em vez de usar comandos de estilo mais fortes.

Limitações

Os modelos de TTS aceitam entradas somente de texto e geram saídas somente de áudio.
A geração de vários locutores com uma única solicitação (multiSpeakerVoiceConfig / vários locutores speakers) é compatível com até dois locutores usando vozes pré-criadas. Para combinar vozes projetadas (voice_...) ou replicadas (voicekey_...) personalizadas em um diálogo com vários personagens, sintetize a vez de cada falante individualmente e concatene os frames de áudio PCM de 24 kHz.
Limites de armazenamento e TTL de voz personalizada:
- Vozes com estado (store=True, solicitadas ou replicadas): máximo de 200 vozes por projeto com um TTL de um ano (time-to-live).
- Chaves de voz sem estado (store=False, voicekey_...): TTL de sete dias (time-to-live).
Consulte a seção Idiomas disponíveis para saber quais idiomas são cobertos.

A seguir

Crie personas vocais personalizadas em linguagem natural com o Design de voz.
Replique a voz de um falante em Replicação de voz.
Compare as especificações dos modelos nas páginas Gemini 3.8 Flash TTS e Gemini 3.8 Flash-Lite TTS.
Confira o áudio bidirecional interativo com a API Live.