A API Gemini pode transformar entradas de texto em áudio de um ou vários falantes usando recursos nativos de geração de texto em voz (TTS). 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. 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 um ou vários locutores com base em texto.
Antes de começar
Use uma variante do modelo Gemini 2.5 com recursos nativos de conversão de texto em voz (TTS), 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 antes de começar a criar.
Conversão de texto em voz com um único locutor
Para converter texto em áudio de um único falante, defina a modalidade de resposta como "audio" e transmita um objeto SpeechConfig com VoiceConfig definido.
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:
Python
from google import genai
from google.genai import types
import wave
# Set up the wave file to save the output:
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()
response = client.models.generate_content(
model="gemini-2.5-flash-preview-tts",
contents="Say cheerfully: Have a wonderful day!",
config=types.GenerateContentConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
voice_config=types.VoiceConfig(
prebuilt_voice_config=types.PrebuiltVoiceConfig(
voice_name='Kore',
)
)
),
)
)
data = response.candidates[0].content.parts[0].inline_data.data
file_name='out.wav'
wave_file(file_name, data) # Saves the file to current directory
JavaScript
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 ai = new GoogleGenAI({});
const response = await ai.models.generateContent({
model: "gemini-2.5-flash-preview-tts",
contents: [{ parts: [{ text: 'Say cheerfully: Have a wonderful day!' }] }],
config: {
responseModalities: ['AUDIO'],
speechConfig: {
voiceConfig: {
prebuiltVoiceConfig: { voiceName: 'Kore' },
},
},
},
});
const data = response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
const audioBuffer = Buffer.from(data, 'base64');
const fileName = 'out.wav';
await saveWaveFile(fileName, audioBuffer);
}
await main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-X POST \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"parts":[{
"text": "Say cheerfully: Have a wonderful day!"
}]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {
"prebuiltVoiceConfig": {
"voiceName": "Kore"
}
}
}
},
"model": "gemini-2.5-flash-preview-tts",
}' | jq -r '.candidates[0].content.parts[0].inlineData.data' | \
base64 --decode >out.pcm
# You may need to install ffmpeg.
ffmpeg -f s16le -ar 24000 -ac 1 -i out.pcm out.wav
Conversão de texto em voz com vários falantes
Para áudio com vários alto-falantes, você precisa de um objeto MultiSpeakerVoiceConfig com
cada alto-falante (até dois) configurado como um SpeakerVoiceConfig.
Você precisa definir cada speaker com os mesmos nomes usados no comando:
Python
from google import genai
from google.genai import types
import wave
# Set up the wave file to save the output:
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?"""
response = client.models.generate_content(
model="gemini-2.5-flash-preview-tts",
contents=prompt,
config=types.GenerateContentConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
multi_speaker_voice_config=types.MultiSpeakerVoiceConfig(
speaker_voice_configs=[
types.SpeakerVoiceConfig(
speaker='Joe',
voice_config=types.VoiceConfig(
prebuilt_voice_config=types.PrebuiltVoiceConfig(
voice_name='Kore',
)
)
),
types.SpeakerVoiceConfig(
speaker='Jane',
voice_config=types.VoiceConfig(
prebuilt_voice_config=types.PrebuiltVoiceConfig(
voice_name='Puck',
)
)
),
]
)
)
)
)
data = response.candidates[0].content.parts[0].inline_data.data
file_name='out.wav'
wave_file(file_name, data) # Saves the file to current directory
JavaScript
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 ai = 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 response = await ai.models.generateContent({
model: "gemini-2.5-flash-preview-tts",
contents: [{ parts: [{ text: prompt }] }],
config: {
responseModalities: ['AUDIO'],
speechConfig: {
multiSpeakerVoiceConfig: {
speakerVoiceConfigs: [
{
speaker: 'Joe',
voiceConfig: {
prebuiltVoiceConfig: { voiceName: 'Kore' }
}
},
{
speaker: 'Jane',
voiceConfig: {
prebuiltVoiceConfig: { voiceName: 'Puck' }
}
}
]
}
}
}
});
const data = response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
const audioBuffer = Buffer.from(data, 'base64');
const fileName = 'out.wav';
await saveWaveFile(fileName, audioBuffer);
}
await main();
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-X POST \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"parts":[{
"text": "TTS the following conversation between Joe and Jane:
Joe: Hows it going today Jane?
Jane: Not too bad, how about you?"
}]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"multiSpeakerVoiceConfig": {
"speakerVoiceConfigs": [{
"speaker": "Joe",
"voiceConfig": {
"prebuiltVoiceConfig": {
"voiceName": "Kore"
}
}
}, {
"speaker": "Jane",
"voiceConfig": {
"prebuiltVoiceConfig": {
"voiceName": "Puck"
}
}
}]
}
}
},
"model": "gemini-2.5-flash-preview-tts",
}' | jq -r '.candidates[0].content.parts[0].inlineData.data' | \
base64 --decode > out.pcm
# You may need to install ffmpeg.
ffmpeg -f s16le -ar 24000 -ac 1 -i out.pcm out.wav
Como 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 TTS de um ou vários locutores. Por exemplo, em um comando de 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 respiração 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.
Python
from google import genai
from google.genai import types
client = genai.Client()
transcript = client.models.generate_content(
model="gemini-2.0-flash",
contents="""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.""").text
response = client.models.generate_content(
model="gemini-2.5-flash-preview-tts",
contents=transcript,
config=types.GenerateContentConfig(
response_modalities=["AUDIO"],
speech_config=types.SpeechConfig(
multi_speaker_voice_config=types.MultiSpeakerVoiceConfig(
speaker_voice_configs=[
types.SpeakerVoiceConfig(
speaker='Dr. Anya',
voice_config=types.VoiceConfig(
prebuilt_voice_config=types.PrebuiltVoiceConfig(
voice_name='Kore',
)
)
),
types.SpeakerVoiceConfig(
speaker='Liam',
voice_config=types.VoiceConfig(
prebuilt_voice_config=types.PrebuiltVoiceConfig(
voice_name='Puck',
)
)
),
]
)
)
)
)
# ...Code to stream or save the output
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
async function main() {
const transcript = await ai.models.generateContent({
model: "gemini-2.0-flash",
contents: "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 response = await ai.models.generateContent({
model: "gemini-2.5-flash-preview-tts",
contents: transcript,
config: {
responseModalities: ['AUDIO'],
speechConfig: {
multiSpeakerVoiceConfig: {
speakerVoiceConfigs: [
{
speaker: "Dr. Anya",
voiceConfig: {
prebuiltVoiceConfig: {voiceName: "Kore"},
}
},
{
speaker: "Liam",
voiceConfig: {
prebuiltVoiceConfig: {voiceName: "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:
| Zephyr: Bright | Puck: Upbeat | Charon: informativa |
| Kore: Firme | Fenrir: Excitável | Leda: Juventude |
| Orus: Firm | Aoede: Breezy | Callirrhoe -- Tranquila |
| Autonoe: Bright | Enceladus: Breathy | Iapetus: Limpar |
| Umbriel: tranquilo | Algieba: Suave | Despina -- Smooth |
| Erinome: Limpar | Algenib: Gravelly | Rasalgethi: informativa |
| Laomedeia: Upbeat | Achernar: suave | Alnilam: Firme |
| Schedar: Even | Gacrux: Adulto | Pulcherrima: Avançar |
| Achird: Amigável | Zubenelgenubi: Casual | Vindemiatrix: Gentil |
| Sadachbia: Lively | Sadaltager: Conhecedor | Sulafat: quente |
Você pode ouvir todas as opções de voz no AI Studio.
Idiomas compatíveis
Os modelos de TTS detectam automaticamente o idioma de entrada. Elas oferecem suporte aos seguintes 24 idiomas:
| Idioma | Código BCP-47 | Idioma | Código BCP-47 |
|---|---|---|---|
| Árabe (egípcio) | ar-EG |
Alemão (Alemanha) | de-DE |
| Inglês (EUA) | en-US |
Espanhol (EUA) | es-US |
| Francês (França) | fr-FR |
Hindi (Índia) | hi-IN |
| Indonésio (Indonésia) | id-ID |
Italiano (Itália) | it-IT |
| Japonês (Japão) | ja-JP |
Coreano (Coreia) | ko-KR |
| Português (Brasil) | pt-BR |
Russo (Rússia) | ru-RU |
| Holandês (Países Baixos) | nl-NL |
Polonês (Polônia) | pl-PL |
| Tailandês (Tailândia) | th-TH |
Turco (Turquia) | tr-TR |
| Vietnamita (Vietnã) | vi-VN |
Romeno (Romênia) | ro-RO |
| Ucraniano (Ucrânia) | uk-UA |
Bengali (Bangladesh) | bn-BD |
| Inglês (Índia) | Pacote en-IN e hi-IN |
Marati (Índia) | mr-IN |
| Tâmil (Índia) | ta-IN |
Telugo (Índia) | te-IN |
Modelos compatíveis
| Modelo | Falante único | Multispeaker |
|---|---|---|
| Prévia do Gemini 2.5 Flash TTS | ✔️ | ✔️ |
| Pré-lançamento da TTS do Gemini 2.5 Pro | ✔️ | ✔️ |
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.
Guia de comandos
O modelo Gemini Native Audio Generation Text-to-Speech (TTS) se diferencia dos modelos tradicionais de TTS por usar um modelo de linguagem grande que sabe não apenas o que dizer, mas também como dizer.
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 principal e o arquétipo do personagem; uma descrição da cena que estabelece o ambiente físico e a "vibe" emocional; e observações do diretor que oferecem uma orientação de performance mais precisa 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 percepção 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ções fundamentais 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!
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 de personagem, 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. Alguns exemplos são estilo, respiração, ritmo, articulação e sotaque.
- Contexto de exemplo: oferece ao modelo um ponto de partida contextual para que o 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 fornecidas.
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
Vamos detalhar cada elemento do comando.
Perfil de áudio
Descreva brevemente a personalidade do personagem.
- Nome. Dar um nome ao personagem ajuda a fundamentar o modelo e a melhorar o desempenho. Mencione o personagem pelo nome ao definir a cena e o contexto.
- Função. 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 estritas 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 nível de detalhe 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 coisas como animado, energético, 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 simplesmente dizer "enérgico e entusiasmado".
Você pode até tentar termos populares no setor de narração, como "sorriso vocal". Você pode combinar quantas características de estilo quiser.
Exemplos:
Simple Emotion
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").
Accent:
Descreva o sotaque desejado. Quanto mais específico você for, melhores serão os resultados. Por exemplo, use "Sotaque 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 detalhes
### 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 AI Studio, use nosso app TTS e deixe o Gemini assumir a direção. Confira algumas dicas para fazer ótimas performances vocais:
- Não se esqueça de manter todo 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.
A seguir
- Confira o manual de geração de áudio.
- 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.