Criar uma voz personalizada com design de voz

Você pode 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 pré-criada ou gravar um áudio de referência, você cria uma voz descrevendo a idade, o timbre, o sotaque e a forma de falar 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 projetadas 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

  1. Criar uma voz com solicitação: chame o método create da API Voices com voice.type definido como VOICE_TYPE_PROMPTED e store definido como true.
  2. Receber um ID de voz e uma amostra: a API Voices gera a voz, armazena no seu projeto e retorna o ID dela (por exemplo, voice_abc123...) no campo id e uma amostra da voz no campo sample_audio.
  3. Gerar fala: transmita o ID da voz em speechConfig.voiceConfig.voice ao chamar generateContent ou streamGenerateContent.

Antes de começar

Conclua as etapas em Antes de começar na página de 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 ser true. As vozes criadas 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 com store: true falham com um erro INVALID_ARGUMENT.

A criação de uma voz pode levar alguns segundos. A amostra 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 campo data contém o áudio codificado em base64, e o campo mime_type nomeia a codificação. Por exemplo, audio/l16; rate=24000; channels=1 é PCM de 16 bits sem cabeçalho a 24 kHz, mono.

  • usage: o número de tokens usados na 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. Raw 16-bit PCM (audio/l16) needs a WAV header.
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.pcm

Se sample_audio.mime_type for audio/l16, o arquivo voice_sample.pcm vai conter áudio PCM de 16 bits sem cabeçalho a 24 kHz, mono.

Para ouvir a voz com seu próprio texto, gere a fala com ela, conforme mostrado na próxima seção.

Gerar fala com uma voz projetada

Transmita o ID de 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, receber e excluir as vozes armazenadas no seu projeto, incluindo vozes projetadas e vozes replicadas armazenadas. O método list retorna as vozes armazenadas no projeto, seguidas pelas vozes predefinidas e da Biblioteca de vozes avançada. Para listar apenas as vozes armazenadas no seu projeto, defina o filtro type como prompted e replicated, como fazem os exemplos a seguir. O método get também retorna a amostra de uma voz projetada 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 reinicia esse período. Assim, uma voz que você usa regularmente não expira. 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 create vai retornar um erro RESOURCE_EXHAUSTED. Aguarde e tente de novo. Para mais informações, consulte Cotas e limites do sistema.

Preços

A criação de uma voz projetada é cobrada como tokens de entrada de texto e tokens de saída de áudio nas taxas do Gemini 3.8 Flash TTS. Os tokens de saída de áudio abrangem a amostra de voz gerada pela API Voices. O campo usage na resposta create informa as duas contagens. Por exemplo, a descrição de uma frase no criar exemplo 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 cobrados. A fala gerada com uma voz projetada é cobrada de acordo com as taxas do modelo que você chama.

Para conferir 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.style para emoções situacionais: depois de criar a voz, use valores style curtos, como "whispered urgently" ou "cheerful and energetic", para direcionar cada turno sem mudar a identidade do falante.
  • Seja específico e conciso: uma descrição clara de uma ou duas frases, como "Uma locutora esportiva enérgica e objetiva na casa dos 30 anos com um leve sotaque do meio-oeste", produz resultados mais consistentes do que um parágrafo longo ou contraditório.

A seguir