Criar uma voz personalizada com o remix de voz

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

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:

  1. Escolha uma voz base e descreva as mudanças: chame o método create da API Voices com voice.type definido como VOICE_TYPE_PROMPTED, store definido como true, voice.prompted.base_voice definido como o nome ou ID de uma voz atual e voice.prompted.input definido como uma descrição das mudanças.
  2. 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 campo id e uma amostra da voz no campo sample_audio. A voz base não muda.
  3. Gerar fala ou remixar novamente: transmita o novo ID de voz em speechConfig.voiceConfig.voice ao chamar generateContent ou streamGenerateContent. Para refinar ainda mais a voz, transmita o novo ID de voz como o base_voice de outra solicitação create.

Antes de começar

  1. Instale a CLI do Google Cloud.

  2. Configure a CLI gcloud para usar sua identidade federada.

    Para mais informações, consulte Fazer login na CLI gcloud com sua identidade federada.

  3. Para inicializar a CLI gcloud, execute o seguinte comando:

    gcloud init
  4. 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ão resourcemanager.projects.create. Saiba como conceder papéis.
    • Crie um projeto do Cloud de Confiance :

      gcloud projects create PROJECT_ID

      Substitua PROJECT_ID por 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_ID pelo nome do projeto do Cloud de Confiance .

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

  6. Verifique se o faturamento está ativado para o projeto do Cloud de Confiance .

  7. 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
  8. 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 :

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 ser true. As vozes remixadas são sempre armazenadas no seu projeto. As solicitações que definem base_voice com store: false falham com um erro INVALID_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 ID voice_... de uma voz criada ou remixada. Se a voz não existir, a solicitação vai falhar com um erro NOT_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 campo data contém o áudio codificado em base64, e o campo mime_type nomeia 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, verifique mime_type antes 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 create da 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_voice de 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 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 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.input peç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_audio antes de fazer a próxima mudança.
  • Use o remix para características permanentes e speech_metadata.style para 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 de speech_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