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 conversão de texto em voz é controlável, o que significa que você pode combinar metadados de turno estruturados (speech_metadata) e tags vocais inline para orientar o estilo, o sotaque, o ritmo e o tom do áudio.

O recurso de TTS é diferente da geração de fala fornecida pela API Live, que foi projetada para áudio interativo e não estruturado e entradas e saídas multimodais. Enquanto a API Live se destaca em contextos de conversação dinâmicos, a TTS pela API Gemini é adaptada para cenários que exigem a leitura exata de textos com controle detalhado sobre o estilo e o som, como a geração de podcasts ou audiolivros.

Este guia mostra como gerar áudio de uma ou várias pessoas com base em texto usando 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 de TTS do Gemini listado na seção Modelos compatíveis e faça upgrade para o SDK da IA generativa do Google mais recente (google-genai >= 2.25.0 para Python ou @google/genai >= 2.24.0 para JavaScript/TypeScript) ou use a API REST. Para melhores resultados, consulte Quando usar cada modelo para selecionar o melhor modelo para sua carga de trabalho.

Talvez seja útil testar os modelos de TTS do Gemini 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 de TTS do Gemini 3.8, transmita a transcrição literal em input, anexe o estilo de nível de turno 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 de saída WAV padrão (audio/wav) do modelo diretamente em um arquivo:

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))

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();

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" }
      ]
    }
  }' | jq -r '[.steps[] | select(.type=="model_output") | .content[] | select(.type=="audio")] | last | .data' | base64 --decode > out.wav

Nos SDKs para Python e JavaScript, é possível recuperar dados de áudio gerados usando a propriedade de conveniência interaction.output_audio, que retorna o último bloco de áudio gerado. Em respostas JSON REST brutas, o áudio codificado em base64 é armazenado em steps[].content[].data. Para detalhes sobre propriedades de conveniência, consulte a Visão geral das interações.

TTS com vários locutores

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. Observe que speech_config aceita uma matriz ([{"voice": "..."}]) para geração de locutor único e um objeto ({"speakers": [...]}) para geração de vários locutores:

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": {
            "speakers": [
                {"speaker": "Joe", "voice": "Puck"},
                {"speaker": "Jane", "voice": "Kore"},
            ],
        }
    },
)

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

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: {
            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();

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 instruções de palco sejam lidas em voz alta, divida as instruções por escopo:

• Entrega sustentada no nível da fala (speech_metadata.style): coloque emoções, estilo de entrega, prosódia, ritmo e volume que se aplicam a uma fala 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 que não sejam de 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.

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": "Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Dr. Anya",
                    "style": "whispered urgently",
                }],
            },
            {
                "type": "text",
                "text": "<gasp> No way! <laugh> We've been searching for this species all season!",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Liam",
                    "style": "warm and enthusiastic",
                }],
            },
        ],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": {
            "speakers": [
                {"speaker": "Dr. Anya", "voice": "Kore"},
                {"speaker": "Liam", "voice": "Puck"},
            ],
        }
    },
)

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

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: 'Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?',
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Dr. Anya',
                  style: 'whispered urgently',
               }],
            },
            {
               type: 'text',
               text: "<gasp> No way! <laugh> We've been searching for this species all season!",
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Liam',
                  style: 'warm and enthusiastic',
               }],
            },
         ],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: {
            speakers: [
               { speaker: 'Dr. Anya', voice: 'Kore' },
               { speaker: 'Liam', voice: 'Puck' },
            ],
         },
      },
   });

   if (interaction.output_audio?.data) {
      const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
      fs.writeFileSync('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.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Dr. Anya",
            "style": "whispered urgently"
          }]
        },
        {
          "type": "text",
          "text": "<gasp> No way! <laugh> We'\''ve been searching for this species all season!",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Liam",
            "style": "warm and enthusiastic"
          }]
        }
      ]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": {
        "speakers": [
          { "speaker": "Dr. Anya", "voice": "Kore" },
          { "speaker": "Liam", "voice": "Puck" }
        ]
      }
    }
  }'

Geração de fala em streaming

É possível transmitir o áudio gerado enquanto ele está sendo 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 16 bits assinados little-endian lineares PCM (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.

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)

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();

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). É 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 de 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:

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

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))

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();

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:

1. Vozes de estúdio predefinidas:30 vozes selecionadas listadas na tabela a seguir.
2. Biblioteca de voz estendida:centenas de vozes adicionais em vários idiomas, sotaques e arquétipos de personagens acessíveis usando client.voices.list() (GET /v1beta/voices).
3. 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).
4. Replicação de voz:replique a voz de um locutor usando áudios 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 personalizada

* Extensão de TTL:a janela de retenção de um ano é redefinida sempre que a voz é usada ativamente (sintetizando a fala com a voz ou usando-a como uma voz base para remixagem). As vozes sem atividade por um ano são excluídas automaticamente.

Vozes predefinidas

Biblioteca de vozes e filtragem estendidas

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

ListVoices retorna as vozes personalizadas armazenadas (ordenadas da mais recente para a mais antiga), seguidas pelas vozes do catálogo pré-criadas que correspondem aos 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 são combinados com AND:

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}"
    )

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}`
  );
}

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 mais de 130 idiomas, e o Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) aceita mais de 100 idiomas:

Modelos compatíveis

Quando usar cada modelo

Os dois modelos de TTS do Gemini 3.8 compartilham o mesmo esquema de API e formato de comando, 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 com nuances e o controle expressivo forem prioridades. Ele é ideal para trabalhos criativos de nível de estúdio, 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 uma voz sólida e estabilidade de tom de 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 de conversação, recursos de leitura em voz alta, replicação de voz confiável e fala diária de um único locutor 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:

1. Mova as instruções 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 estruturadas speech_metadata em vez de incorporar rubricas no texto da transcrição.
2. Use tags inline com colchetes angulares apenas para eventos vocais pontuais:mantenha vocalizações e pausas momentâneas sem 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.
3. Especifique speaker em cada turno em solicitações com vários locutores:cada turno em uma solicitação com vários locutores precisa incluir explicitamente speaker dentro de speech_metadata correspondente a um dos locutores configurados.
4. Crie personas de design com o design de voz:substitua blocos de vários parágrafos "Audio Profile" ou "Director's Notes" por uma voz personalizada criada em Design de voz e transmita esse ID voice_... nas solicitações de TTS com strings style mínimas ou vazias.
5. 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), a TTS do Gemini 3.8 retorna áudio WAV (audio/wav) com um cabeçalho RIFF padrão por padrão para solicitações unárias.
   • Se o código já tiver encapsulado 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 sem cabeçalho, mu-law ou A-law, defina explicitamente response_format.mime_type como "audio/l16", "audio/mulaw" ou "audio/alaw" (por exemplo, {"response_format": {"type": "audio", "mime_type": "audio/l16"}} na API Interactions ou AUDIO_L16 em generateContent). 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 Gemini 3.8 TTS 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, defina a persona com antecedência em Design de voz e use style apenas para ajustes opcionais em cada interação.
• Eventos pontuais (tags inline): coloque explosões vocais momentâneas que não sejam de fala, respirações ou pausas inline dentro da transcrição usando colchetes angulares (<cough>, <breath>, <sigh>, <short pause>). Use colchetes angulares (<...>) para obter a melhor qualidade do áudio e use vocalizações humanas em vez de efeitos sonoros não vocais.

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 locutor deve fazer uma pausa: text Hold on, let me think... <short pause> Alright, I've got it.
• Ritmo no nível da fala:defina "style": "speaking rapidly" ou "style": "speaking slowly" em speech_metadata para controlar a taxa de fala em toda a fala.

Prosódia e tom

Use speech_metadata.style para controlar a prosódia, o tom 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 colocar ênfase vocal natural em palavras-chave:

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

Sons não verbais e explosões vocais

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

Backchannels e fala sobreposta

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

• Trocas curtas no backchannel:insira reações breves do ouvinte (|oh hmm|, |oh really?|, |absolutely|) na vez do falante ativo:
  • Turno 1 (falante 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 (Locutor 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 por "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 com antecedência no design de voz em vez de usar blocos de estilo longos:parágrafos longos de "Audio Profile" e listas com vários marcadores de "Director's Notes" transferidos de modelos anteriores são a causa mais comum de desvio 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 TTS do Gemini 3.8 são treinados para se ancorar primeiro na referência de áudio. Não inclua instruções que digam ao modelo para manter a voz estável (como "do not switch speaker identity" ou "maintain identical timbre"). O texto extra do 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 locutor 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 Estendida ou crie uma com o Voice Design.

Fluxo de trabalho recomendado

1. 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-alvo e à persona.
2. 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").
3. Teste primeiro a TTS simples:sintetize sua transcrição com um campo style vazio primeiro. A maioria das solicitações não precisa de nenhuma instrução style.
4. 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 linha de base consistente.

Agentes de voz e diálogo multiturno

Ao criar agentes de voz de conversação em tempo real ou aplicativos de várias rodadas:

• Faça uma chamada de TTS por turno à medida que os blocos de texto do LLM chegam.
• Permita que o voice configurado (voice_... pré-criado, projetado ou voice_... / voicekey_... replicado) carregue a identidade do falante em todas as interações. Nunca reenvie uma persona de personagem longa em cada interação.
• Deixe o campo style por turno vazio ou envie uma string constante curta (como "casual, friendly") para toda a conversa.
• Divida as respostas longas do agente em turnos mais curtos em vez de usar prompts 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 com vários locutores em uma única solicitação (speech_config.speakers) aceita até dois locutores usando vozes pré-criadas. Para combinar vozes personalizadas (voice_...) ou replicadas (voice_... / voicekey_...) em diálogos com vários personagens, sintetize a fala de cada falante individualmente. Como as solicitações unárias retornam audio/wav com um cabeçalho RIFF de 44 bytes por padrão, solicite PCM bruto ({"type": "audio", "mime_type": "audio/l16"}) ou remova o cabeçalho WAV de cada turno antes de concatenar os frames de áudio PCM de 24 kHz.
• Limites de armazenamento de voz personalizada e TTL:
  • 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 compatíveis para saber mais sobre a cobertura de idiomas.

A seguir

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