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 texto em voz (TTS) do Gemini. A geração de conversão de texto em voz (TTS) é controlável, ou seja, você pode usar a linguagem natural para estruturar interações e 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. Embora a API Live seja excelente 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 um ou vários locutores com base em texto.

Antes de começar

Use uma variante do modelo Gemini 2.5 com recursos de conversão de texto em voz (TTS) do Gemini, conforme listado na seção Modelos compatíveis. Para ter os melhores resultados, considere qual modelo se adapta melhor ao seu caso de uso específico.

Talvez seja útil [testar os modelos TTS do Gemini 2.5 no AI Studio]

TTS com uma única voz

Para converter texto em áudio de um único falante, defina a modalidade de resposta como "audio" e transmita um objeto speech_config com um nome de voz. Você precisa escolher um nome de voz nas vozes de saída predefinidas.

Este exemplo salva o áudio de saída do modelo em um arquivo wave:

from google import genai
import wave

def wave_file(filename, pcm, channels=1, rate=24000, sample_width=2):
    with wave.open(filename, "wb") as wf:
        wf.setnchannels(channels)
        wf.setsampwidth(sample_width)
        wf.setframerate(rate)
        wf.writeframes(pcm)

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.1-flash-tts-preview",
    input="Say cheerfully: Have a wonderful day!",
    response_modalities=["audio"],
    speech_config=[
        {"voice": "Kore"}
    ]
)

data = None
for step in interaction.steps:
    for content_block in step.content:
        if content_block.type == "audio":
            data = content_block.data
            break
    if data:
        break
wave_file('out.wav', data)

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

async function saveWaveFile(
   filename,
   pcmData,
   channels = 1,
   rate = 24000,
   sampleWidth = 2,
) {
   return new Promise((resolve, reject) => {
      const writer = new wav.FileWriter(filename, {
            channels,
            sampleRate: rate,
            bitDepth: sampleWidth * 8,
      });

      writer.on('finish', resolve);
      writer.on('error', reject);

      writer.write(pcmData);
      writer.end();
   });
}

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

   const interaction = await client.interactions.create({
      model: "gemini-3.1-flash-tts-preview",
      input: "Say cheerfully: Have a wonderful day!",
      response_modalities: ['audio'],
      speech_config: [
         { voice: 'Kore' }
      ],
   });

   let data = null;
   for (const step of interaction.steps) {
      for (const contentBlock of step.content) {
         if (contentBlock.type === 'audio') {
            data = contentBlock.data;
            break;
         }
      }
      if (data) break;
   }
   const audioBuffer = Buffer.from(data, 'base64');
   await saveWaveFile('out.wav', audioBuffer);
}
await main();

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.1-flash-tts-preview",
    "input": "Say cheerfully: Have a wonderful day!",
    "response_modalities": ["audio"],
    "speech_config": [
      { "voice": "Kore" }
    ]
  }'

TTS com vários locutores

Para áudio com vários alto-falantes, você precisa de um objeto multi_speaker_voice_config com cada alto-falante (até dois) configurado como um speaker_voice_config. Você precisa definir cada speaker com os mesmos nomes usados no comando:

from google import genai
import wave

def wave_file(filename, pcm, channels=1, rate=24000, sample_width=2):
   with wave.open(filename, "wb") as wf:
      wf.setnchannels(channels)
      wf.setsampwidth(sample_width)
      wf.setframerate(rate)
      wf.writeframes(pcm)

client = genai.Client()

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

 interaction = client.interactions.create(
     model="gemini-3.1-flash-tts-preview",
     input=prompt,
     response_modalities=["audio"],
     speech_config=[
         {"speaker": "Joe", "voice": "Kore"},
         {"speaker": "Jane", "voice": "Puck"}
     ]
 )

data = None
for step in interaction.steps:
   for content_block in step.content:
      if content_block.type == "audio":
         data = content_block.data
         break
   if data:
      break
wave_file('out.wav', data)

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

async function saveWaveFile(
   filename,
   pcmData,
   channels = 1,
   rate = 24000,
   sampleWidth = 2,
) {
   return new Promise((resolve, reject) => {
      const writer = new wav.FileWriter(filename, {
            channels,
            sampleRate: rate,
            bitDepth: sampleWidth * 8,
      });

      writer.on('finish', resolve);
      writer.on('error', reject);

      writer.write(pcmData);
      writer.end();
   });
}

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

   const prompt = `TTS the following conversation between Joe and Jane:
         Joe: How's it going today Jane?
         Jane: Not too bad, how about you?`;

   const interaction = await client.interactions.create({
      model: "gemini-3.1-flash-tts-preview",
      input: prompt,
      response_modalities: ['audio'],
      speech_config: [
         { speaker: 'Joe', voice: 'Kore' },
         { speaker: 'Jane', voice: 'Puck' }
      ]
   });

   let data = null;
   for (const step of interaction.steps) {
      for (const contentBlock of step.content) {
         if (contentBlock.type === 'audio') {
            data = contentBlock.data;
            break;
         }
      }
      if (data) break;
   }
   const audioBuffer = Buffer.from(data, 'base64');
   await saveWaveFile('out.wav', audioBuffer);
}

await main();

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.1-flash-tts-preview",
  "input": "TTS the following conversation between Joe and Jane: Joe: Hows it going today Jane? Jane: Not too bad, how about you?",
  "response_modalities": ["audio"],
  "speech_config": [
    { "speaker": "Joe", "voice": "Kore" },
    { "speaker": "Jane", "voice": "Puck" }
  ]
}'

Controlar o estilo de fala com comandos

Você pode controlar o estilo, o tom, o sotaque e o ritmo usando comandos em linguagem natural para conversão de texto em fala com um ou vários locutores. Por exemplo, em um comando com um único falante, você pode dizer:

Say in an spooky whisper:
"By the pricking of my thumbs...
Something wicked this way comes"

Em um comando com vários falantes, forneça ao modelo o nome de cada um e a transcrição correspondente. Você também pode dar orientações para cada pessoa individualmente:

Make Speaker1 sound tired and bored, and Speaker2 sound excited and happy:

Speaker1: So... what's on the agenda today?
Speaker2: You're never going to guess!

Use uma opção de voz que corresponda ao estilo ou à emoção que você quer transmitir para enfatizar ainda mais. No comando anterior, por exemplo, a voz ofegante de Encélado pode enfatizar "cansado" e "entediado", enquanto o tom alegre de Puck pode complementar "animado" e "feliz".

Gerar um comando para converter em áudio

Os modelos de TTS só geram áudio, mas você pode usar outros modelos para gerar uma transcrição primeiro e depois transmitir essa transcrição ao modelo de TTS para leitura em voz alta.

from google import genai

client = genai.Client()

transcript_interaction = client.interactions.create(
   model="gemini-3-flash-preview",
   input="""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."""
)
transcript = transcript_interaction.steps[-1].content[0].text

tts_interaction = client.interactions.create(
   model="gemini-3.1-flash-tts-preview",
   input=transcript,
   response_modalities=["audio"],
   speech_config=[
      {"speaker": "Dr. Anya", "voice": "Kore"},
      {"speaker": "Liam", "voice": "Puck"}
   ]
)

# ...Code to stream or save the output

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

const client = new GoogleGenAI({});

async function main() {

const transcriptInteraction = await client.interactions.create({
   model: "gemini-3-flash-preview",
   input: "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.",
   })

const ttsInteraction = await client.interactions.create({
   model: "gemini-3.1-flash-tts-preview",
   input: transcriptInteraction.steps.at(-1).content[0].text,
   response_modalities: ['audio'],
   speech_config: [
      { speaker: "Dr. Anya", voice: "Kore" },
      { speaker: "Liam", voice: "Puck" }
   ]
  });
}
// ..JavaScript code for exporting .wav file for output audio

await main();

Opções de voz

Os modelos de TTS são compatíveis com as seguintes 30 opções de voz no campo voice_name:

Você pode ouvir todas as opções de voz em

Idiomas compatíveis

Os modelos de TTS detectam automaticamente o idioma de entrada. Os seguintes idiomas são aceitos:

Modelos compatíveis

Guia de comandos

O modelo Gemini Native Audio Generation Text-to-Speech (TTS) se diferencia dos modelos convencionais de TTS por usar um modelo de linguagem grande que sabe não apenas o que dizer, mas também como dizer.

Pense em um comando avançado como uma instrução do sistema para o modelo seguir. É uma maneira de dar ao modelo mais contexto e controle sobre o desempenho.

Para aproveitar esse recurso, os usuários podem se imaginar como diretores definindo uma cena para um talento de voz virtual. Para criar um comando, recomendamos considerar os seguintes componentes: um perfil de áudio que define a identidade e o arquétipo principais do personagem; uma descrição da cena que estabelece o ambiente físico e a "vibe" emocional; e observações do diretor que oferecem orientações de performance mais precisas sobre estilo, sotaque e controle de ritmo.

Ao fornecer instruções sutis, como um sotaque regional preciso, recursos paralinguísticos específicos (por exemplo, respiração) ou ritmo, os usuários podem aproveitar a capacidade de reconhecimento de contexto do modelo para gerar performances de áudio altamente dinâmicas, naturais e expressivas. Para um desempenho ideal, recomendamos que a transcrição e os comandos de direção estejam alinhados, para que "quem está dizendo" corresponda a "o que está sendo dito" e "como está sendo dito".

O objetivo deste guia é oferecer orientação fundamental e gerar ideias ao desenvolver experiências de áudio usando a geração de áudio do Gemini TTS. Estamos ansiosos para ver o que você vai criar!

Tags de áudio

As tags são modificadores inline, como [whispers] ou [laughs], que oferecem controle granular sobre a veiculação. Use-os para mudar o tom, o ritmo e a vibe emocional de uma linha ou seção da transcrição. Você também pode usar esses recursos para adicionar interjeições e alguns outros sons não verbais à performance, como [cough], [sighs] ou [gasp].

Não há uma lista exaustiva do que funciona ou não. Recomendamos testar diferentes emoções e expressões para ver como a saída muda.

Se a transcrição não estiver em inglês, recomendamos que você use tags de áudio em inglês para ter os melhores resultados.

Use a criatividade com as tags de áudio

Para mostrar o tipo de variabilidade que você pode ter com as tags de áudio, aqui estão alguns exemplos que dizem a mesma coisa, mas a entrega muda com base nas tags usadas.

Você pode mudar a ênfase da entrega adicionando tags no início de uma linha para deixar o alto-falante animado, entediado ou relutante:

• [excitedly] Olá! Sou um novo modelo de conversão de texto em voz e posso dizer as coisas de várias maneiras diferentes. Como posso ajudar?
• [bored] Olá, sou um novo modelo de conversão de texto em voz…
• [reluctantly] Olá, sou um novo modelo de conversão de texto em voz…

As tags também podem ser usadas para mudar o ritmo da entrega ou combinar ritmo com ênfase:

• [very fast] Olá, sou um novo modelo de conversão de texto em voz…
• [very slow] Olá, sou um novo modelo de conversão de texto em voz…
• [sarcastically, one painfully slow word at a time] Olá, sou um novo modelo de conversão de texto em voz…

Você também tem controle preciso sobre seções específicas, o que significa que pode sussurrar uma parte e gritar outra.

• [whispers] Olá, sou um novo modelo de conversão de texto em voz, [shouting] e posso dizer as coisas de várias maneiras diferentes. [whispers] Como posso ajudar?

Você também pode testar qualquer ideia criativa:

• [like a cartoon dog] Olá, sou um novo modelo de conversão de texto em voz…
• [like dracula] Olá, sou um novo modelo de conversão de texto em voz…

As tags usadas com frequência incluem:

As tags oferecem controle rápido sobre a entrega da transcrição. Para ter ainda mais controle, combine-as com um comando de contexto para definir o tom e a atmosfera geral da performance.

Estrutura do comando

Um comando robusto inclui os seguintes elementos que se unem para criar uma ótima performance:

• Perfil de áudio: estabelece uma persona para a voz, definindo uma identidade, um arquétipo e outras características, como idade, histórico etc.
• Cena: define o cenário. Descreve o ambiente físico e a "vibe".
• Observações do diretor: orientações de performance em que você pode detalhar quais instruções são importantes para o talento virtual. Exemplos são estilo, respiração, ritmo, articulação e sotaque.
• Exemplo de contexto: dá ao modelo um ponto de partida contextual para que seu ator virtual entre na cena que você configurou de forma natural.
• Transcrição: o texto que o modelo vai falar. Para obter os melhores resultados, lembre-se de que o tema da transcrição e o estilo de escrita devem estar de acordo com as instruções que você está fornecendo.
• Tags de áudio: modificadores que podem ser inseridos em uma transcrição para mudar a forma como essa parte do texto é entregue, como [whispers] ou [shouting].

Exemplo de comando completo:

# AUDIO PROFILE: Jaz R.
## "The Morning Hype"

## THE SCENE: The London Studio
It is 10:00 PM in a glass-walled studio overlooking the moonlit London skyline,
but inside, it is blindingly bright. The red "ON AIR" tally light is blazing.
Jaz is standing up, not sitting, bouncing on the balls of their heels to the
rhythm of a thumping backing track. Their hands fly across the faders on a
massive mixing desk. It is a chaotic, caffeine-fueled cockpit designed to wake
up an entire nation.

### DIRECTOR'S NOTES
Style:
* The "Vocal Smile": You must hear the grin in the audio. The soft palate is
always raised to keep the tone bright, sunny, and explicitly inviting.
* Dynamics: High projection without shouting. Punchy consonants and elongated
vowels on excitement words (e.g., "Beauuutiful morning").

Pace: Speaks at an energetic pace, keeping up with the fast music.  Speaks
with A "bouncing" cadence. High-speed delivery with fluid transitions - no dead
air, no gaps.

Accent: Jaz is from Brixton, London

### SAMPLE CONTEXT
Jaz is the industry standard for Top 40 radio, high-octane event promos, or any
script that requires a charismatic Estuary accent and 11/10 infectious energy.

#### TRANSCRIPT
Yes, massive vibes in the studio! You are locked in and it is absolutely
popping off in London right now. If you're stuck on the tube, or just sat
there pretending to work... stop it. Seriously, I see you. Turn this up!
We've got the project roadmap landing in three, two... let's go!

Estratégias detalhadas de comandos

Analise cada elemento do comando da seguinte maneira:

Perfil de áudio

Descreva brevemente a personalidade do personagem.

• Nome. Dar um nome ao personagem ajuda a fundamentar o modelo e a melhorar a performance. Refira-se ao personagem pelo nome ao definir a cena e o contexto.
• Papel. Identidade principal e arquétipo do personagem que está atuando na cena, por exemplo, DJ de rádio, podcaster, repórter de notícias etc.

Exemplos:

# AUDIO PROFILE: Jaz R.
## "The Morning Hype"

# AUDIO PROFILE: Monica A.
## "The Beauty Influencer"

Cenário

Defina o contexto da cena, incluindo local, clima e detalhes ambientais que estabelecem o tom e a atmosfera. Descreva o que está acontecendo ao redor do personagem e como isso o afeta. A cena oferece o contexto ambiental para toda a interação e orienta a atuação de maneira sutil e orgânica.

Exemplos:

## THE SCENE: The London Studio
It is 10:00 PM in a glass-walled studio overlooking the moonlit London skyline,
but inside, it is blindingly bright. The red "ON AIR" tally light is blazing.
Jaz is standing up, not sitting, bouncing on the balls of their heels to the
rhythm of a thumping backing track. Their hands fly across the faders on a
massive mixing desk. It is a chaotic, caffeine-fueled cockpit designed to
wake up an entire nation.

## THE SCENE: Homegrown Studio
A meticulously sound-treated bedroom in a suburban home. The space is
deadened by plush velvet curtains and a heavy rug, but there is a
distinct "proximity effect."

Observações do diretor

Esta seção importante inclui orientações específicas sobre performance. Você pode pular todos os outros elementos, mas recomendamos que inclua este.

Defina apenas o que é importante para a performance, tomando cuidado para não especificar demais. Muitas regras restritas limitam a criatividade dos modelos e podem resultar em uma performance pior. Equilibre a descrição da função e da cena com as regras específicas de performance.

As instruções mais comuns são Estilo, ritmo e sotaque, mas o modelo não se limita a elas nem as exige. Inclua instruções personalizadas para abordar outros detalhes importantes para sua performance e forneça o máximo ou o mínimo de detalhes necessário.

Exemplo:

### DIRECTOR'S NOTES

Style: Enthusiastic and Sassy GenZ beauty YouTuber

Pacing: Speaks at an energetic pace, keeping up with the extremely fast, rapid
delivery influencers use in short form videos.

Accent: Southern california valley girl from Laguna Beach |

Estilo:

Define o tom e o estilo da fala gerada. Inclua palavras como "animado", "enérgico", "relaxado", "entediado" etc. para orientar a performance. Seja descritivo e forneça o máximo de detalhes possível: "Entusiasmo contagiante. O ouvinte precisa sentir que faz parte de um evento comunitário enorme e emocionante" funciona melhor do que dizer "enérgico e entusiasmado".

Você pode até tentar termos populares no setor de narração, como "sorriso vocal". Você pode adicionar quantas características de estilo quiser.

Exemplos:

Emoção simples

DIRECTORS NOTES
...
Style: Frustrated and angry developer who can't get the build to run.
...

Mais profundidade

DIRECTORS NOTES
...
Style: Sassy GenZ beauty YouTuber, who mostly creates content for YouTube Shorts.
...

Complexo

DIRECTORS NOTES
Style:
* The "Vocal Smile": You must hear the grin in the audio. The soft palate is
always raised to keep the tone bright, sunny, and explicitly inviting.
*Dynamics: High projection without shouting. Punchy consonants and
elongated vowels on excitement words (e.g., "Beauuutiful morning").

Sotaque:

Descreva o sotaque selecionado. Quanto mais específico for o comando, melhores serão os resultados. Por exemplo, use "Sotaque inglês britânico como ouvido em Croydon, Inglaterra" em vez de "Sotaque britânico".

Exemplos:

### DIRECTORS NOTES
...
Accent: Southern california valley girl from Laguna Beach
...

### DIRECTORS NOTES
...
Accent: Jaz is a from Brixton, London
...

Ritmo:

Ritmo geral e variação de ritmo ao longo da matéria.

Exemplos:

Simples

### DIRECTORS NOTES
...
Pacing: Speak as fast as possible
...

Mais profundidade

### DIRECTORS NOTES
...
Pacing: Speaks at a faster, energetic pace, keeping up with fast paced music.
...

Complexo

### DIRECTORS NOTES
...
Pacing: The "Drift": The tempo is incredibly slow and liquid. Words bleed into each other. There is zero urgency.
...

Experimente

Teste alguns desses exemplos no app TTS e deixe o Gemini assumir a direção. Confira algumas dicas para fazer ótimas performances vocais:

• Mantenha o comando coerente. O roteiro e a direção trabalham juntos para criar uma ótima performance.
• Não é necessário descrever tudo. Às vezes, dar espaço para o modelo preencher as lacunas ajuda a manter a naturalidade. (Assim como um ator talentoso)
• Se você estiver com dificuldades, peça ajuda ao Gemini para criar seu roteiro ou apresentação.

Limitações

• Os modelos de TTS só podem receber entradas de texto e gerar saídas de áudio.
• Uma sessão de TTS tem um limite de janela de contexto de 32 mil tokens.
• Consulte a seção Idiomas para saber quais idiomas são aceitos.
• A TTS não oferece suporte a streaming.

As restrições a seguir se aplicam especificamente ao usar o modelo de pré-lançamento da TTS do Gemini 3.1 Flash para geração de fala:

• Inconsistência de voz com as instruções do comando:a saída do modelo nem sempre corresponde ao falante selecionado, fazendo com que o áudio soe diferente do esperado. Para evitar tons incompatíveis (como uma voz masculina grave tentando falar como uma menina), verifique se o tom e o contexto da sua solicitação escrita estão alinhados naturalmente com o perfil do locutor selecionado.
• Qualidade de saídas mais longas:a qualidade e a consistência da fala podem começar a diminuir com saídas geradas que duram mais de alguns minutos. Recomendamos dividir as transcrições em partes menores.
• Retornos ocasionais de tokens de texto:o modelo às vezes retorna tokens de texto em vez de tokens de áudio, fazendo com que o servidor falhe na solicitação com um erro 500. Como isso ocorre aleatoriamente em uma porcentagem muito pequena de solicitações, implemente uma lógica de novas tentativas automatizada no aplicativo para lidar com elas.
• Rejeições falsas do classificador de comandos:comandos vagos podem não acionar o classificador de síntese de voz, resultando em uma solicitação rejeitada (PROHIBITED_CONTENT) ou fazendo com que o modelo leia em voz alta as instruções de estilo e as observações do diretor. Valide seus comandos adicionando um preâmbulo claro instruindo o modelo a sintetizar a fala e rotule explicitamente onde a transcrição falada real começa.

A seguir

• A API Live do Gemini oferece opções interativas de geração de áudio que podem ser intercaladas com outras modalidades.
• Para trabalhar com entradas de áudio, consulte o guia Compreensão de áudio.