É possível criar uma voz personalizada com base em uma descrição em linguagem natural usando o recurso de
design de voz. Em vez de escolher uma voz predefinida ou gravar
um áudio de referência, você cria uma voz descrevendo a idade, o timbre
vocal, o sotaque e a entrega básica de um personagem. A API Voices armazena a voz no seu
projeto e retorna um ID voice_... reutilizável que você transmite em solicitações de geração
de fala.
As vozes criadas funcionam 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).
Como funciona o design de voz
- Criar uma voz com comando: chame o método
createda API Voices comvoice.typedefinido comoVOICE_TYPE_PROMPTEDestoredefinido comotrue. - Receber um ID de voz e uma amostra: a API Voices gera a voz,
armazena-a no projeto e retorna o ID (por exemplo,
voice_abc123...) no campoide uma amostra da voz no camposample_audio. - Gerar fala: transmita o ID da voz em
speechConfig.voiceConfig.voiceao chamargenerateContentoustreamGenerateContent.
Antes de começar
Conclua as etapas em
Antes de começar
na página da TTS do Gemini. A API Voices está disponível no local global
pela versão v1beta1 da API.
Criar uma voz projetada
Defina os seguintes campos na solicitação:
store: precisa sertrue. As vozes projetadas são sempre armazenadas no seu projeto.voice.type:VOICE_TYPE_PROMPTED.voice.prompted.input: uma descrição em linguagem natural da voz.voice.display_name,voice.gender,voice.language_code: metadados opcionais para a voz.
Não defina voice.model. As solicitações que definem um modelo junto com
store: true falham com um erro INVALID_ARGUMENT.
A criação de uma voz pode levar alguns segundos. O exemplo em Python define o tempo limite da solicitação como 60 segundos.
A resposta contém os seguintes campos:
id: o ID da nova voz.sample_audio: uma amostra da voz. O campodatacontém o áudio codificado em base64, e o campomime_typenomeia a codificação. Por padrão, a amostra é um arquivo WAV completo (audio/wav) com um cabeçalho RIFF: PCM de 16 bits, 24 kHz, mono. Algumas vozes podem retornar PCM de 16 bits sem cabeçalho (audio/l16; rate=24000; channels=1). Portanto, verifiquemime_typeantes de salvar o áudio.usage: o número de tokens usados pela solicitação. Para saber mais informações, consulte Preços.
Python
import base64
import wave
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
voice = client.voices.create(
store=True,
voice={
"type": "VOICE_TYPE_PROMPTED",
"display_name": "Warm British Astronomer",
"gender": "male",
"language_code": "en-GB",
"prompted": {
"input": (
"A warm, thoughtful astronomer in his late 60s with a gentle"
" British accent, speaking with quiet wonder."
)
},
},
timeout=60,
)
print(f"Created voice ID: {voice.id}")
# Save the voice sample. The SDK returns sample_audio.data as a base64
# string. By default, it's a complete WAV file (audio/wav). For
# compatibility, add a WAV header if the sample is raw 16-bit PCM
# (audio/l16).
sample = base64.b64decode(voice.sample_audio.data)
if voice.sample_audio.mime_type.lower().startswith("audio/l16"):
with wave.open("voice_sample.wav", "wb") as wf:
wf.setnchannels(1)
wf.setsampwidth(2)
wf.setframerate(24000)
wf.writeframes(sample)
else:
with open("voice_sample.wav", "wb") as f:
f.write(sample)
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices \
-d '{
"store": true,
"voice": {
"type": "VOICE_TYPE_PROMPTED",
"displayName": "Warm British Astronomer",
"gender": "male",
"languageCode": "en-GB",
"prompted": {
"input": "A warm, thoughtful astronomer in his late 60s with a gentle British accent, speaking with quiet wonder."
}
}
}' > created_voice.json
# Print the voice ID and the encoding of the voice sample.
jq -r '.id, .sample_audio.mime_type' created_voice.json
# Decode the voice sample.
jq -r '.sample_audio.data' created_voice.json | base64 --decode > voice_sample.wav
Por padrão, sample_audio.mime_type é audio/wav, e o arquivo voice_sample.wav é um arquivo WAV completo. Se mime_type for
audio/l16, o arquivo vai conter áudio PCM de 16 bits sem cabeçalho a 24 kHz, mono,
e vai precisar de um cabeçalho WAV para que a maioria dos players possa abri-lo.
Para ouvir a voz com seu próprio texto, gere uma fala com ela, conforme mostrado na próxima seção. Para mudar algumas características da voz mais tarde sem descrevê-la novamente, use o remix de voz.
Gerar fala com uma voz projetada
Transmita o ID da voz em speechConfig.voiceConfig.voice:
Python
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
response = client.models.generate_content(
model="gemini-3.8-flash-tts",
contents=[{
"role": "user",
"parts": [{
"text": (
"Look out past the rings of Saturn. Those faint photons left"
" their source millions of years ago."
),
"speech_metadata": {"style": "reflective and awe-inspired"},
}],
}],
config={
"response_modalities": ["AUDIO"],
"speech_config": {"voice_config": {"voice": "VOICE_ID"}},
},
)
# The SDK has already decoded the base64 audio, so inline_data.data is a
# complete WAV file by default.
with open("designed_voice.wav", "wb") as f:
f.write(response.candidates[0].content.parts[0].inline_data.data)
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent \
-d '{
"contents": [{
"role": "user",
"parts": [{
"text": "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
"speechMetadata": {"style": "reflective and awe-inspired"}
}]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {"voice": "VOICE_ID"}
}
}
}' | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 --decode > designed_voice.wav
Substitua VOICE_ID pelo ID de voz retornado pelo método
create.
Gerenciar vozes armazenadas
É possível listar, acessar e excluir as vozes armazenadas no seu projeto, incluindo
vozes projetadas,
vozes remixadas e
vozes replicadas armazenadas.
O método list retorna as vozes armazenadas no projeto, seguidas pelas vozes pré-criadas e da Biblioteca de Vozes Estendida. Para listar apenas as vozes armazenadas no projeto, defina o filtro type
como prompted e replicated, como nos exemplos a seguir. O tipo prompted
inclui vozes projetadas e remixadas. O método get também retorna
a amostra de uma voz criada ou remixada no campo sample_audio.
Python
from google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
# List the voices stored in your project.
for voice in client.voices.list(type_=["prompted", "replicated"]).voices or []:
print(voice.id, voice.display_name, voice.type)
# Get a voice by ID.
voice = client.voices.get(id="VOICE_ID")
# Delete a voice.
client.voices.delete(id="VOICE_ID")
REST
# List the voices stored in your project.
curl -G \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices \
--data-urlencode "type=prompted" \
--data-urlencode "type=replicated"
# Get a voice by ID.
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices/VOICE_ID
# Delete a voice.
curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices/VOICE_ID
Limites
- As vozes armazenadas expiram um ano após o último uso. Gerar fala com uma voz ou usá-la como base para um remix reinicia esse período, para que uma voz usada regularmente não expire. Exclua as vozes que não são mais necessárias.
- As solicitações de criação de voz estão sujeitas a uma cota por projeto e por minuto. Se
você exceder esse limite, o método
createvai retornar um erroRESOURCE_EXHAUSTED. Aguarde e tente de novo. Para mais informações, consulte Cotas e limites do sistema.
Preços
A criação de uma voz personalizada é cobrada como tokens de entrada de texto e tokens de saída de áudio de acordo com as taxas do Gemini 3.8 Flash TTS. Os tokens de saída de áudio cobrem a
amostra de voz que a API Voices gera. O campo usage na resposta create
informa as duas contagens. Por exemplo, a descrição de uma frase no
exemplo de criação usa cerca de 220 tokens de entrada e cerca de 1.100 tokens de
saída.
Os métodos get, list e delete não são faturados. A fala gerada
com uma voz criada é cobrada de acordo com as taxas do modelo que você chama.
Para saber as taxas de token, consulte Preços do Gemini Enterprise.
Práticas recomendadas para comandos
- Coloque características permanentes na descrição da voz: defina idade, gênero,
timbre, textura vocal e sotaque regional ao criar a voz, não
em
speech_metadata.style. - Use
speech_metadata.stylepara emoções situacionais: depois de criar a voz, use valores curtos destyle, como"whispered urgently"ou"cheerful and energetic", para direcionar cada turno sem mudar a identidade do locutor. - Seja específico e conciso: uma descrição clara de uma ou duas frases, como "Uma locutora esportiva enérgica e de voz clara, na faixa dos 30 anos, com um leve sotaque do Centro-Oeste", produz resultados mais consistentes do que um parágrafo longo ou contraditório.
A seguir
- Edite uma voz criada ou predefinida com o Remix de voz.
- Replique a voz de um locutor com a replicação de voz.
- Aprenda mais sobre estilo por turno, tags inline e diálogos com vários locutores em Gerar fala com o Gemini TTS.