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, ou seja, é possível combinar metadados estruturados de turno (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 do 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 uma única pessoa com os modelos Gemini 3.8 TTS, transmita a transcrição literal em parts[].text, anexe o estilo no nível da vez em parts[].speech_metadata e configure sua voz em speechConfig.voiceConfig. Você pode transmitir um nome de voz predefinido, um ID da biblioteca de voz estendida, um ID de design de voz personalizado (voice_...) ou um ID de replicação de voz (voice_... ou voicekey_... sem estado opcional).

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

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {"style": "cheerful and friendly"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "voice_config": {"voice": "Kore"}
        },
    },
)

data = response.candidates[0].content.parts[0].inline_data.data
with open("out.wav", "wb") as f:
    f.write(data)

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

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

   const response = await ai.models.generateContent({
      model: 'gemini-3.8-flash-tts',
      contents: [{
         role: 'user',
         parts: [{
            text: 'Have a wonderful day!',
            speechMetadata: { style: 'cheerful and friendly' },
         }],
      }],
      config: {
         responseModalities: ['AUDIO'],
         speechConfig: {
            voiceConfig: { voice: 'Kore' },
         },
      },
   });

   const data = response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
   const audioBuffer = Buffer.from(data, 'base64');

   fs.writeFileSync('out.wav', audioBuffer);
}
await main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash-tts:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "contents": [{
          "role": "user",
          "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {
              "style": "cheerful and friendly"
            }
          }]
        }],
        "generationConfig": {
          "responseModalities": ["AUDIO"],
          "speechConfig": {
            "voiceConfig": {
              "voice": "Kore"
            }
          }
        }
    }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | \
          base64 --decode > out.wav

TTS com vários falantes

Para diálogos com vários participantes, configure dois falantes em multiSpeakerVoiceConfig.speakerVoiceConfigs usando prebuiltVoiceConfig e transmita cada turno do diálogo como um part separado com speech_metadata especificando speaker e style opcional no nível do turno:

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [
            {
                "text": "How's it going today Jane?",
                "speech_metadata": {
                    "speaker": "Joe",
                    "style": "cheerful and friendly",
                },
            },
            {
                "text": "Not too bad, how about you? Ready to test these new voices?",
                "speech_metadata": {
                    "speaker": "Jane",
                    "style": "calm and relaxed",
                },
            },
        ],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "multi_speaker_voice_config": {
                "speaker_voice_configs": [
                    {
                        "speaker": "Joe",
                        "voice_config": {
                            "prebuilt_voice_config": {"voice_name": "Puck"}
                        },
                    },
                    {
                        "speaker": "Jane",
                        "voice_config": {
                            "prebuilt_voice_config": {"voice_name": "Kore"}
                        },
                    },
                ]
            }
        },
    },
)

data = response.candidates[0].content.parts[0].inline_data.data
with open("out.wav", "wb") as f:
    f.write(data)

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

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

   const response = await ai.models.generateContent({
      model: 'gemini-3.8-flash-tts',
      contents: [{
         role: 'user',
         parts: [
            {
               text: "How's it going today Jane?",
               speechMetadata: {
                  speaker: 'Joe',
                  style: 'cheerful and friendly',
               },
            },
            {
               text: 'Not too bad, how about you? Ready to test these new voices?',
               speechMetadata: {
                  speaker: 'Jane',
                  style: 'calm and relaxed',
               },
            },
         ],
      }],
      config: {
         responseModalities: ['AUDIO'],
         speechConfig: {
            multiSpeakerVoiceConfig: {
               speakerVoiceConfigs: [
                  {
                     speaker: 'Joe',
                     voiceConfig: {
                        prebuiltVoiceConfig: { voiceName: 'Puck' },
                     },
                  },
                  {
                     speaker: 'Jane',
                     voiceConfig: {
                        prebuiltVoiceConfig: { voiceName: 'Kore' },
                     },
                  },
               ],
            },
         },
      },
   });

   const data = response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
   const audioBuffer = Buffer.from(data, 'base64');

   fs.writeFileSync('out.wav', audioBuffer);
}

await main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash-tts:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [
        {
          "text": "How'\''s it going today Jane?",
          "speech_metadata": {
            "speaker": "Joe",
            "style": "cheerful and friendly"
          }
        },
        {
          "text": "Not too bad, how about you? Ready to test these new voices?",
          "speech_metadata": {
            "speaker": "Jane",
            "style": "calm and relaxed"
          }
        }
      ]
    }],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "multiSpeakerVoiceConfig": {
          "speakerVoiceConfigs": [
            {
              "speaker": "Joe",
              "voiceConfig": {
                "prebuiltVoiceConfig": { "voiceName": "Puck" }
              }
            },
            {
              "speaker": "Jane",
              "voiceConfig": {
                "prebuiltVoiceConfig": { "voiceName": "Kore" }
              }
            }
          ]
        }
      }
    }
  }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | \
      base64 --decode > out.wav

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 em speech_metadata.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.

Opções de voz

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

1. Vozes predefinidas do Studio:30 vozes selecionadas listadas na tabela a seguir.
2. 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).
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 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

* 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 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:

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

Ao fazer upgrade de modelos de pré-lançamento anteriores (gemini-3.1-flash-tts-preview ou gemini-2.5-pro-preview-tts) para o Gemini 3.8 TTS (gemini-3.8-flash-tts ou gemini-3.8-flash-lite-tts), confira estas cinco mudanças principais:

1. Separe o estilo da transcrição:mova as instruções de atuação, tom, prosódia e ritmo (como "whispering", "out of breath" ou "speaking slowly") do texto simples para speech_metadata.style. Mantenha text estritamente como a transcrição literal mais as tags vocais inline.
2. 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_... pelas solicitações de TTS com strings style mínimas ou vazias.
3. Use turnos de diálogo estruturados:para diálogos com vários locutores, transmita um part por turno de locutor com speech_metadata.speaker em vez de incorporar prefixos Speaker: ... em um único bloco de texto.
4. Use colchetes angulares para tags vocais inline:use colchetes angulares (<laugh>, <sigh>, <cough>, <breath>, <short pause>) para vocalizações e pausas humanas em um determinado momento. Evite tags de efeitos sonoros não vocais, como aplausos ou ruídos.
5. Considerar a saída WAV (AUDIO_WAV) padrão em solicitações unárias:ao contrário de gemini-3.1-flash-tts-preview (que retornava PCM bruto sem cabeçalho AUDIO_L16 por padrão), os modelos de TTS do Gemini 3.8 retornam áudio WAV (AUDIO_WAV) completo com um cabeçalho RIFF (24 kHz, mono, PCM de 16 bits) em 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 o pacote wav do Node), remova o wrapper de cabeçalho manual e grave os bytes de áudio decodificados diretamente em um arquivo .wav.
   • Se o pipeline atual exigir áudio PCM bruto sem cabeçalho, mu-law ou A-law, defina explicitamente response_format.audio.mime_type como "AUDIO_L16", "AUDIO_MULAW" ou "AUDIO_ALAW" (por exemplo, {"response_format": {"audio": {"mime_type": "AUDIO_L16"}}} em generateContent ou {"response_format": {"type": "audio", "mime_type": "audio/l16"}} na API Interactions). 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, defina 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.

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:

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

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 e à persona de destino.
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 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.
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.

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.

Geração de fala por streaming

Você pode transmitir o áudio gerado enquanto ele é sintetizado pelo modelo. 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 por padrão blocos brutos de 16 bits sem cabeçalho, little-endian, lineares PCM (AUDIO_L16 / audio/L16;codec=pcm;rate=24000, 24 kHz, mono). Assim, os blocos de áudio podem ser reproduzidos ou concatenados continuamente sem cabeçalhos de contêiner:

from google import genai

client = genai.Client()

response_stream = client.models.generate_content_stream(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {"style": "cheerful and friendly"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {
            "voice_config": {"voice": "Kore"}
        },
    },
)

for chunk in response_stream:
    try:
        data = chunk.candidates[0].content.parts[0].inline_data.data
        # data contains raw PCM bytes (24kHz, 1-channel, 16-bit)
    except (IndexError, AttributeError):
        pass

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

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

   const responseStream = await ai.models.generateContentStream({
      model: 'gemini-3.8-flash-tts',
      contents: [{
         role: 'user',
         parts: [{
            text: 'Have a wonderful day!',
            speechMetadata: { style: 'cheerful and friendly' },
         }],
      }],
      config: {
         responseModalities: ['AUDIO'],
         speechConfig: {
            voiceConfig: { voice: 'Kore' },
         },
      },
   });

   for await (const chunk of responseStream) {
      const data = chunk.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
      if (data) {
         const audioBuffer = Buffer.from(data, 'base64');
         // Process the audio buffer
      }
   }
}
await main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash-tts:streamGenerateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "contents": [{
          "role": "user",
          "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {
              "style": "cheerful and friendly"
            }
          }]
        }],
        "generationConfig": {
          "responseModalities": ["AUDIO"],
          "speechConfig": {
            "voiceConfig": {
              "voice": "Kore"
            }
          }
        }
    }'

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 (models.generate_content): retornam áudio WAV (AUDIO_WAV) completo com um cabeçalho RIFF (24 kHz, mono, PCM little-endian de 16 bits com sinal). É possível gravar os bytes de áudio decodificados diretamente em um arquivo .wav sem adicionar manualmente um contêiner WAV.
• Solicitações de streaming (models.generate_content_stream / streamGenerateContent): retornam blocos PCM linear bruto sem cabeçalho (AUDIO_L16) (24 kHz, mono, PCM little-endian de 16 bits com sinal) por padrão para que os blocos possam ser transmitidos ou concatenados continuamente sem cabeçalhos de contêiner em cada bloco.

É possível substituir a codificação e a taxa de amostragem do áudio de saída usando generationConfig.responseFormat.audio:

Também é possível especificar sampleRate (por exemplo, 24000, 16000 ou 8000 Hz; o padrão é 24000 Hz).

O exemplo a seguir solicita PCM bruto de 16 bits sem cabeçalho (AUDIO_L16) a 24 kHz:

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash-tts",
    contents=[{
        "role": "user",
        "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {"style": "cheerful and friendly"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "response_format": {
            "audio": {
                "mime_type": "AUDIO_L16",
                "sample_rate": 24000,
            }
        },
        "speech_config": {
            "voice_config": {"voice": "Kore"}
        },
    },
)

data = response.candidates[0].content.parts[0].inline_data.data
with open("out.pcm", "wb") as f:
    f.write(data)

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

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

   const response = await ai.models.generateContent({
      model: 'gemini-3.8-flash-tts',
      contents: [{
         role: 'user',
         parts: [{
            text: 'Have a wonderful day!',
            speechMetadata: { style: 'cheerful and friendly' },
         }],
      }],
      config: {
         responseModalities: ['AUDIO'],
         responseFormat: {
            audio: {
               mimeType: 'AUDIO_L16',
               sampleRate: 24000,
            },
         },
         speechConfig: {
            voiceConfig: { voice: 'Kore' },
         },
      },
   });

   const data = response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
   const audioBuffer = Buffer.from(data, 'base64');

   fs.writeFileSync('out.pcm', audioBuffer);
}
await main();

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash-tts:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "contents": [{
          "role": "user",
          "parts": [{
            "text": "Have a wonderful day!",
            "speech_metadata": {
              "style": "cheerful and friendly"
            }
          }]
        }],
        "generationConfig": {
          "responseModalities": ["AUDIO"],
          "responseFormat": {
            "audio": {
              "mimeType": "AUDIO_L16",
              "sampleRate": 24000
            }
          },
          "speechConfig": {
            "voiceConfig": {
              "voice": "Kore"
            }
          }
        }
    }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | \
          base64 --decode > out.pcm

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) aceita até dois locutores usando vozes pré-criadas. Para combinar vozes personalizadas (voice_...) ou replicadas (voice_... / voicekey_...) em um diálogo com vários personagens, sintetize a vez 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 (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 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.