É possível criar uma nova voz personalizada editando uma voz atual com o recurso de
remixagem de voz. Em vez de descrever uma voz do zero, escolha
uma voz base e descreva as mudanças que quer fazer, como idade, tom,
energia, timbre ou sotaque diferentes. A API Voices armazena o resultado como uma nova voz no
seu projeto e retorna um ID voice_... reutilizável que você transmite em solicitações de geração
de fala.
Você pode remixar as seguintes vozes:
- Uma voz predefinida,
como
PuckouKore. - Uma voz da Biblioteca de Vozes Estendida.
- Uma voz projetada ou uma voz remixada anteriormente que está armazenada no seu projeto.
As vozes remixadas 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 remix de voz
A remixagem de voz usa o mesmo método create da API Voices que o
design de voz, com o
campo voice.prompted.base_voice adicionado:
- Escolha uma voz base e descreva as mudanças: chame o método
createda API Voices comvoice.typedefinido comoVOICE_TYPE_PROMPTED,storedefinido comotrue,voice.prompted.base_voicedefinido como o nome ou ID de uma voz atual evoice.prompted.inputdefinido como uma descrição das mudanças. - Receber um novo ID de voz e uma amostra: a API Voices aplica as
mudanças à voz base, armazena o resultado como uma nova voz no
projeto e retorna o ID (por exemplo,
voice_abc123...) no campoide uma amostra da voz no camposample_audio. A voz base não muda. - Gerar fala ou remixar novamente: transmita o novo ID de voz em
speechConfig.voiceConfig.voiceao chamargenerateContentoustreamGenerateContent. Para refinar ainda mais a voz, transmita o novo ID de voz como obase_voicede outra solicitaçãocreate.
Antes de começar
-
Instale a CLI do Google Cloud.
-
Configure a CLI gcloud para usar sua identidade federada.
Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.
-
Para inicializar a CLI gcloud, execute o seguinte comando:
gcloud init -
Crie ou selecione um projeto do Cloud de Confiance .
Papéis necessários para selecionar ou criar um projeto
- Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. É possível selecionar qualquer projeto em que você tenha recebido um papel.
-
Criar um projeto: para criar um projeto, é preciso ter o papel de Criador de projetos
(
roles/resourcemanager.projectCreator), que contém a permissãoresourcemanager.projects.create. Saiba como conceder papéis.
-
Crie um projeto do Cloud de Confiance :
gcloud projects create PROJECT_ID
Substitua
PROJECT_IDpor um nome para o projeto do Cloud de Confiance que você está criando. -
Selecione o projeto do Cloud de Confiance que você criou:
gcloud config set project PROJECT_ID
Substitua
PROJECT_IDpelo nome do projeto do Cloud de Confiance .
-
Se este guia estiver usando um projeto atual, verifique se você tem as permissões necessárias para concluir o guia. Se você criou um projeto, já tem as permissões necessárias.
-
Verifique se o faturamento está ativado para o projeto do Cloud de Confiance .
Ative a API Agent Platform, se ainda não estiver ativada:
Funções necessárias para ativar APIs
Para ativar APIs, você precisa da permissão
serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.gcloud services enable aiplatform.googleapis.com
-
Crie credenciais de autenticação local para sua conta de usuário:
gcloud auth application-default login
Se um erro de autenticação for retornado, confirme se você fez login na CLI gcloud com sua identidade federada.
Para usar os exemplos em Python, instale a versão 2.33.0 ou mais recente do SDK de IA generativa do Google:
pip install --upgrade "google-genai>=2.33.0"
A API Voices está disponível no local global pela versão v1beta1 da API.
Funções exigidas
Para receber as permissões necessárias para remixar vozes e gerar falas com elas, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto do Cloud de Confiance by S3NS :
-
Criar, listar, receber e excluir vozes e gerar fala:
Usuário da Agent Platform (
roles/aiplatform.user)
Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.
Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.
Criar uma voz remixada
Defina os seguintes campos na solicitação:
store: precisa sertrue. As vozes remixadas são sempre armazenadas no seu projeto. As solicitações que definembase_voicecomstore: falsefalham com um erroINVALID_ARGUMENT.voice.type:VOICE_TYPE_PROMPTED.voice.prompted.base_voice: a voz que será remixada. Use o nome de uma voz predefinida (por exemplo,Puck), o ID de uma voz da Biblioteca de Vozes Estendida ou o IDvoice_...de uma voz criada ou remixada. Se a voz não existir, a solicitação vai falhar com um erroNOT_FOUND.voice.prompted.input: uma descrição em linguagem natural das mudanças a serem feitas na voz base.voice.display_name,voice.gender,voice.language_code: metadados opcionais para a nova voz.
Não defina voice.model. As solicitações que definem um modelo junto com
store: true falham com um erro INVALID_ARGUMENT.
Remixar 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.prompted.base_voice: a voz base que você remixou.sample_audio: uma amostra da nova 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.
As amostras a seguir remixam a voz pré-criada Puck:
Python
Instalar
pip install --upgrade google-genai
Para saber mais, consulte a documentação de referência do SDK.
Defina variáveis de ambiente para usar o SDK de IA generativa do Google com a Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
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": "Older British Puck",
"prompted": {
"base_voice": "Puck",
"input": (
"Make the voice sound slightly older and more grounded, with a"
" warm British accent and measured audiobook narration pacing."
),
},
},
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("remixed_voice_sample.wav", "wb") as wf:
wf.setnchannels(1)
wf.setsampwidth(2)
wf.setframerate(24000)
wf.writeframes(sample)
else:
with open("remixed_voice_sample.wav", "wb") as f:
f.write(sample)
REST
Antes de usar os dados da solicitação abaixo, faça estas substituições:
- PROJECT_ID: o ID do projeto do Cloud de Confiance by S3NS .
Método HTTP e URL:
POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices
Corpo JSON da solicitação:
{
"store": true,
"voice": {
"type": "VOICE_TYPE_PROMPTED",
"displayName": "Older British Puck",
"prompted": {
"baseVoice": "Puck",
"input": "Make the voice sound slightly older and more grounded, with a warm British accent and measured audiobook narration pacing."
}
}
}
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices" | Select-Object -Expand Content
Você receberá uma resposta JSON semelhante a seguinte. O campo sample_audio.data está truncado.
{
"id": "voice_7bd85ebf-761b-4969-8544-4ec60f06d124",
"prompted": {
"base_voice": "Puck"
},
"usage": {
"total_tokens": 578,
"total_input_tokens": 297,
"input_tokens_by_modality": [
{"modality": "text", "tokens": 38},
{"modality": "audio", "tokens": 259}
],
"total_output_tokens": 281,
"output_tokens_by_modality": [
{"modality": "audio", "tokens": 281}
]
},
"sample_audio": {
"mime_type": "audio/wav",
"data": "UklGRpTwAwBXQVZF..."
}
}
Por padrão, sample_audio.mime_type é audio/wav, e
sample_audio.data contém um arquivo WAV completo codificado em base64. Se
mime_type for audio/l16, os dados decodificados serão áudio PCM de 16 bits
sem cabeçalho a 24 kHz, mono, e precisarão de um cabeçalho WAV para que a maioria dos players
possa abri-los.
Gerar fala com uma voz remixada
Transmita o ID da voz em speechConfig.voiceConfig.voice, da mesma forma que você
transmite uma voz criada:
Python
Instalar
pip install --upgrade google-genai
Para saber mais, consulte a documentação de referência do SDK.
Defina variáveis de ambiente para usar o SDK de IA generativa do Google com a Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
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": "Chapter One. The fog rolled quietly across the harbor at dawn.",
"speech_metadata": {"style": "calm and reflective"},
}],
}],
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("remixed_voice.wav", "wb") as f:
f.write(response.candidates[0].content.parts[0].inline_data.data)
REST
Antes de usar os dados da solicitação abaixo, faça estas substituições:
- PROJECT_ID: o ID do projeto do Cloud de Confiance by S3NS .
- VOICE_ID: o ID da voz retornado pelo método
createda API Voices.
Método HTTP e URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent
Corpo JSON da solicitação:
{
"contents": [{
"role": "user",
"parts": [{
"text": "Chapter One. The fog rolled quietly across the harbor at dawn.",
"speechMetadata": {"style": "calm and reflective"}
}]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {"voice": "VOICE_ID"}
}
}
}
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent" | Select-Object -Expand Content
A resposta contém o áudio como um arquivo WAV completo codificado em base64 em candidates[0].content.parts[0].inlineData.data. O campo data está truncado.
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"inlineData": {
"mimeType": "audio/wav",
"data": "UklGRhRlBABXQVZF..."
}
}
]
},
"finishReason": "STOP"
}
]
}
Na amostra do Python, substitua PROJECT_ID pelo ID do projeto do Cloud de Confiance by S3NS
e VOICE_ID pelo ID de voz retornado pelo método
create.
Refinar uma voz passo a passo
Cada voz remixada é uma voz voice_... armazenada, então você pode usá-la como base
para outro remix. Esse fluxo de trabalho detalhado permite que você mude uma ou duas
características por vez e ouça cada resultado antes de fazer a próxima mudança. Também
é possível começar com uma voz projetada.
As amostras a seguir remixam uma voz criada ou remixada:
Python
Instalar
pip install --upgrade google-genai
Para saber mais, consulte a documentação de referência do SDK.
Defina variáveis de ambiente para usar o SDK de IA generativa do Google com a Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
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",
"prompted": {
"base_voice": "BASE_VOICE_ID",
"input": (
"Keep the same speaker identity and accent, but make the"
" delivery calmer, softer, and slightly lower in pitch."
),
},
},
timeout=60,
)
print(f"Created voice ID: {voice.id}")
print(f"Remixed from: {voice.prompted.base_voice}")
REST
Antes de usar os dados da solicitação abaixo, faça estas substituições:
- PROJECT_ID: o ID do projeto do Cloud de Confiance by S3NS .
- BASE_VOICE_ID: o ID do
voice_...de uma voz criada ou remixada no seu projeto.
Método HTTP e URL:
POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices
Corpo JSON da solicitação:
{
"store": true,
"voice": {
"type": "VOICE_TYPE_PROMPTED",
"prompted": {
"baseVoice": "BASE_VOICE_ID",
"input": "Keep the same speaker identity and accent, but make the delivery calmer, softer, and slightly lower in pitch."
}
}
}
Para enviar a solicitação, escolha uma destas opções:
curl
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices"
PowerShell
Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices" | Select-Object -Expand Content
Você receberá uma resposta JSON semelhante a seguinte. O campo sample_audio.data está truncado.
{
"id": "voice_f70c942e-7d78-427d-8466-cae3cb9b0371",
"prompted": {
"base_voice": "voice_7bd85ebf-761b-4969-8544-4ec60f06d124"
},
"sample_audio": {
"mime_type": "audio/wav",
"data": "UklGRhT4AgBXQVZF..."
}
}
No exemplo em Python, substitua BASE_VOICE_ID pelo ID voice_...
de uma voz criada ou remixada no seu projeto.
Gerenciar vozes remixadas
As vozes remixadas são armazenadas no seu projeto com o tipo VOICE_TYPE_PROMPTED,
o mesmo das vozes criadas. Para listar, acessar ou excluir vozes remixadas, use
os mesmos métodos das vozes projetadas. Para mais detalhes, consulte
Gerenciar vozes armazenadas.
Uma voz remixada é independente da voz base:
- A remixagem nunca muda a voz base.
- A exclusão da voz base não afeta as vozes que foram remixadas com base nela.
Limites
- As vozes armazenadas expiram um ano após o último uso. Gerar fala
com uma voz ou usá-la como
base_voicede um remix reinicia esse período. Exclua as vozes que não são mais necessárias. - As solicitações de remix são contabilizadas na mesma cota de criação de voz por projeto e por minuto
que o design e a replicação de voz. 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 remixagem de uma voz é cobrada de acordo com as taxas do Gemini 3.8 Flash TTS para os seguintes tokens:
- Tokens de entrada de texto para a descrição em
voice.prompted.input. - Tokens de entrada de áudio para o áudio de voz base.
- Tokens de saída de áudio para a amostra de voz que a API Voices gera.
O campo usage na resposta create informa cada contagem. Por exemplo, o
remix na amostra de criação usa cerca de 40 tokens de entrada de texto, cerca de
260 tokens de entrada de áudio e cerca de 280 tokens de saída de áudio.
Os métodos get, list e delete não são faturados. A fala gerada
com uma voz remixada é 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
- Descreva apenas as mudanças: o modelo mantém o som da voz base, então descreva apenas as características que devem ser alteradas, como idade, timbre, tom, ritmo ou energia. Não repita a descrição completa da voz.
- Defina um novo idioma ou sotaque explicitamente: um remix mantém o idioma
e o sotaque regional da voz base, a menos que o
voice.prompted.inputpeça um diferente. - Mude uma ou duas características por etapa: ao refinar uma voz em
vários remixes, mude um pequeno conjunto de características em cada solicitação e ouça
o
sample_audioantes de fazer a próxima mudança. - Use o remix para características permanentes e
speech_metadata.stylepara cada turno: use o remix de voz para mudar as características básicas de uma voz, como idade, sotaque, tom ou persona. Use valores curtos despeech_metadata.style, como"whispered urgently"ou"excited", para direcionar a entrega de turnos individuais.
A tabela a seguir mostra exemplos de solicitações de remix:
| Meta | base_voice |
prompted.input |
|---|---|---|
| Mudar idade e timbre | Puck |
Make the voice sound 20 years older with a deeper, slightly
gravelly baritone timbre while keeping the friendly warmth. |
| Mudar o sotaque regional | Kore |
Change the accent to Australian English while preserving the
clear, confident studio delivery. |
| Adaptar a um domínio | Uma voz criada (voice_...) |
Adapt this voice for late-night meditation narration: lower the
vocal projection, slow the pacing, and soften the tone. |
| Aumentar a energia | Uma voz remixada (voice_...) |
Increase vocal energy and projection so the speaker sounds like
an upbeat live event announcer. |
A seguir
- Crie uma voz personalizada com base em uma descrição de texto com o design 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.