Cómo crear una voz personalizada con la remezcla de voz

Puedes crear una voz personalizada nueva editando una voz existente con la función de remezcla de voz. En lugar de describir una voz desde cero, eliges una voz base y describes los cambios que quieres realizar, como una edad, un tono, una energía, un timbre o un acento diferentes. La API de Voices almacena el resultado como una voz nueva en tu proyecto y devuelve un ID de voice_... reutilizable que pasas en las solicitudes de generación de voz.

Puedes crear remixes de las siguientes voces:

Las voces remezcladas funcionan con Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) y Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts).

Cómo funciona la remezcla de voz

La remezcla de voz usa el mismo método create de la API de Voices que el diseño de voz, con el campo voice.prompted.base_voice agregado:

  1. Elige una voz base y describe los cambios: Llama al método create de la API de Voices con voice.type establecido en VOICE_TYPE_PROMPTED, store establecido en true, voice.prompted.base_voice establecido en el nombre o ID de una voz existente y voice.prompted.input establecido en una descripción de los cambios.
  2. Recibe un ID de voz nuevo y una muestra: La API de Voices aplica tus cambios a la voz base, almacena el resultado como una voz nueva en tu proyecto y devuelve su ID (por ejemplo, voice_abc123...) en el campo id y una muestra de la voz en el campo sample_audio. La voz base no cambia.
  3. Vuelve a generar voz o a mezclar: Pasa el nuevo ID de voz en speechConfig.voiceConfig.voice cuando llames a generateContent o streamGenerateContent. Para definir mejor la voz, pasa el ID de voz nuevo como el base_voice de otra solicitud create.

Antes de comenzar

  1. Instala Google Cloud CLI.

  2. Configura gcloud CLI para usar tu identidad federada.

    Para obtener más información, consulta Accede a gcloud CLI con tu identidad federada.

  3. Para inicializar gcloud CLI, ejecuta el siguiente comando:

    gcloud init
  4. Crea o selecciona un proyecto de Cloud de Confiance .

    Roles necesarios para seleccionar o crear un proyecto

    • Seleccionar un proyecto: Seleccionar un proyecto no requiere un rol de IAM específico; puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
    • Crea un proyecto: Para crear un proyecto, necesitas el rol de Creador de proyectos (roles/resourcemanager.projectCreator), que contiene el permiso resourcemanager.projects.create. Obtén más información para otorgar roles.
    • Crea un proyecto de Cloud de Confiance :

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por un nombre para el proyecto de Cloud de Confiance que estás creando.

    • Selecciona el proyecto de Cloud de Confiance que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre de tu proyecto de Cloud de Confiance .

  5. Si usas un proyecto existente en esta guía, verifica que tengas los permisos necesarios para completarla. Si creaste un proyecto nuevo, ya tienes los permisos necesarios.

  6. Verifica que la facturación esté habilitada para tu proyecto de Cloud de Confiance .

  7. Habilita la API de Agent Platform si aún no está habilitada:

    Roles necesarios para habilitar las APIs

    Para habilitar las APIs, necesitas el permiso serviceusage.services.enable. Si creaste el proyecto, es probable que ya tengas este permiso a través del rol de propietario (roles/owner). De lo contrario, puedes obtenerlo a través del rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin). Obtén más información para otorgar roles.

    gcloud services enable aiplatform.googleapis.com
  8. Crea credenciales de autenticación locales para tu cuenta de usuario:

    gcloud auth application-default login

    Si se devuelve un error de autenticación, confirma que accediste a gcloud CLI con tu identidad federada.

Para usar las muestras de Python, instala la versión 2.33.0 o una posterior del SDK de IA generativa de Google:

pip install --upgrade "google-genai>=2.33.0"

La API de Voices está disponible en la ubicación global a través de la versión de la API de v1beta1.

Roles obligatorios

Para obtener los permisos que necesitas para mezclar voces y generar voz con ellas, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto de Cloud de Confiance by S3NS :

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Cómo crear una voz con remix

Establece los siguientes campos en la solicitud:

  • store: Debe ser true. Las voces remezcladas siempre se almacenan en tu proyecto. Las solicitudes que configuran base_voice con store: false fallan con un error INVALID_ARGUMENT.
  • voice.type: VOICE_TYPE_PROMPTED.
  • voice.prompted.base_voice: Es la voz que se usará para el remix. Usa el nombre de la voz para una voz precompilada (por ejemplo, Puck), el ID de voz para una voz de la biblioteca de voces extendida o el ID de voice_... para una voz diseñada o remezclada. Si la voz no existe, la solicitud falla con un error NOT_FOUND.
  • voice.prompted.input: Es una descripción en lenguaje natural de los cambios que se deben realizar en la voz base.
  • voice.display_name, voice.gender, voice.language_code: Metadatos opcionales para la voz nueva.

No establezcas voice.model. Las solicitudes que configuran un modelo junto con store: true fallan con un error INVALID_ARGUMENT.

La remezcla de una voz puede tardar varios segundos. En el ejemplo de Python, se establece el tiempo de espera de la solicitud en 60 segundos.

La respuesta contiene los siguientes campos:

  • id: Es el ID de la voz nueva.
  • prompted.base_voice: Es la voz base que remezclaste.
  • sample_audio: Es una muestra de la voz nueva. El campo data contiene el audio codificado en Base64, y el campo mime_type nombra su codificación. De forma predeterminada, la muestra es un archivo WAV completo (audio/wav) con un encabezado RIFF: PCM de 16 bits, 24 kHz, mono. En cambio, algunas voces pueden devolver PCM de 16 bits sin encabezado (audio/l16; rate=24000; channels=1), por lo que debes verificar mime_type antes de guardar el audio.
  • usage: Es la cantidad de tokens que usó la solicitud. Para obtener más información, consulta Precios.

En las siguientes muestras, se remezcla la voz precompilada Puck:

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Establece variables de entorno para usar el SDK de IA generativa de Google con 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 cualquiera de los datos de solicitud a continuación, haz los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance by S3NS .

Método HTTP y URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: El 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..."
  }
}

De forma predeterminada, sample_audio.mime_type es audio/wav y sample_audio.data contiene un archivo WAV completo codificado en Base64. Si mime_type es audio/l16, los datos decodificados son audio PCM de 16 bits sin encabezado a 24 kHz, mono, y necesitan un encabezado WAV antes de que la mayoría de los reproductores puedan abrirlo.

Genera voz con una voz remezclada

Pasa el ID de voz en speechConfig.voiceConfig.voice, de la misma manera que pasas una voz diseñada:

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Establece variables de entorno para usar el SDK de IA generativa de Google con 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 cualquiera de los datos de solicitud a continuación, haz los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance by S3NS .
  • VOICE_ID: Es el ID de voz que devolvió el método create de la API de Voices.

Método HTTP y URL:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

La respuesta contiene el audio como un archivo WAV completo codificado en base64 en candidates[0].content.parts[0].inlineData.data. El campo data está truncado.

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "audio/wav",
              "data": "UklGRhRlBABXQVZF..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

En la muestra de Python, reemplaza PROJECT_ID por el ID del proyecto de Cloud de Confiance by S3NS y VOICE_ID por el ID de voz que devolvió el método create.

Cómo mejorar una voz paso a paso

Cada voz remezclada es una voz de voice_... almacenada, por lo que puedes usarla como la voz base de otro remix. Este flujo de trabajo paso a paso te permite cambiar uno o dos rasgos a la vez y escuchar cada resultado antes de realizar el siguiente cambio. También puedes comenzar con una voz diseñada.

En los siguientes ejemplos, se remezcla una voz diseñada o remezclada existente:

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Establece variables de entorno para usar el SDK de IA generativa de Google con 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 cualquiera de los datos de solicitud a continuación, haz los siguientes reemplazos:

  • PROJECT_ID: Es el ID del proyecto de Cloud de Confiance by S3NS .
  • BASE_VOICE_ID: Es el ID de voice_... de una voz diseñada o remezclada en tu proyecto.

Método HTTP y URL:

POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: El 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..."
  }
}

En el ejemplo de Python, reemplaza BASE_VOICE_ID por el ID de voice_... de una voz diseñada o remezclada en tu proyecto.

Administra las voces de remix

Las voces remezcladas se almacenan en tu proyecto con el tipo VOICE_TYPE_PROMPTED, el mismo tipo que las voces diseñadas. Para enumerar, obtener o borrar voces remezcladas, usa los mismos métodos que para las voces diseñadas. Para obtener más información, consulta Administra las voces almacenadas.

Una voz remezclada es independiente de su voz base:

  • La mezcla nunca cambia la voz base.
  • Borrar la voz base no afecta a las voces que se remezclaron a partir de ella.

Límites

  • Las voces almacenadas vencen un año después de su último uso. Generar voz con una voz o usarla como base_voice de un remix reinicia este período. Borra las voces que ya no necesites.
  • Las solicitudes de remix se consideran dentro de la misma cuota de creación de voz por proyecto y por minuto que el diseño y la replicación de voz. Si lo superas, el método create devuelve un error RESOURCE_EXHAUSTED. Espera y vuelve a intentarlo. Para obtener más información, consulta Cuotas y límites del sistema.

Precios

La remezcla de una voz se factura según las tarifas de Gemini 3.8 Flash TTS para los siguientes tokens:

  • Tokens de entrada de texto para la descripción en voice.prompted.input.
  • Tokens de entrada de audio para el audio de voz base.
  • Tokens de salida de audio para la muestra de voz que genera la API de Voices.

El campo usage de la respuesta create informa cada recuento. Por ejemplo, el remix en la muestra de creación usa alrededor de 40 tokens de entrada de texto, alrededor de 260 tokens de entrada de audio y alrededor de 280 tokens de salida de audio.

No se facturan los métodos get, list ni delete. La voz que generas con una voz remezclada se factura según las tarifas del modelo al que llamas.

Para conocer las tarifas de los tokens, consulta Precios de Gemini Enterprise.

Prácticas recomendadas para escribir instrucciones

  • Describe solo los cambios: El modelo conserva el sonido de la voz base, por lo que solo debes describir los rasgos que quieres cambiar, como la edad, el timbre, el tono, el ritmo o la energía. No repitas la descripción completa de la voz.
  • Indica un idioma o acento nuevo de forma explícita: Un remix conserva el idioma y el acento regional de la voz base, a menos que voice.prompted.input solicite uno diferente.
  • Cambia uno o dos rasgos por paso: Cuando ajustes una voz en varias mezclas, cambia un conjunto pequeño de rasgos en cada solicitud y escucha el sample_audio antes de realizar el siguiente cambio.
  • Usa la remezcla para los rasgos permanentes y speech_metadata.style para cada turno: Usa la remezcla de voz para cambiar la línea de base de una voz, como su edad, acento, tono o persona. Usa valores cortos de speech_metadata.style, como "whispered urgently" o "excited", para dirigir la entrega de turnos individuales.

En la siguiente tabla, se muestran ejemplos de solicitudes de remix:

Objetivo base_voice prompted.input
Cambia la edad y el timbre Puck Make the voice sound 20 years older with a deeper, slightly gravelly baritone timbre while keeping the friendly warmth.
Cambiar el acento regional Kore Change the accent to Australian English while preserving the clear, confident studio delivery.
Cómo adaptar un modelo a un dominio Una voz diseñada (voice_...) Adapt this voice for late-night meditation narration: lower the vocal projection, slow the pacing, and soften the tone.
Aumentar la energía Una voz con remix (voice_...) Increase vocal energy and projection so the speaker sounds like an upbeat live event announcer.

¿Qué sigue?

  • Crea una voz personalizada a partir de una descripción de texto con el diseño de voz.
  • Replica la voz de un interlocutor existente con la replicación de voz.
  • Obtén más información sobre el diseño a nivel de turno, las etiquetas intercaladas y el diálogo de varios interlocutores en Genera voz con Gemini TTS.