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:
- Una voz precompilada,
como
PuckoKore. - Es una voz de la biblioteca de voces extendida.
- Una voz diseñada o una voz remezclada anteriormente que se almacena en tu proyecto.
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:
- Elige una voz base y describe los cambios: Llama al método
createde la API de Voices convoice.typeestablecido enVOICE_TYPE_PROMPTED,storeestablecido entrue,voice.prompted.base_voiceestablecido en el nombre o ID de una voz existente yvoice.prompted.inputestablecido en una descripción de los cambios. - 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 campoidy una muestra de la voz en el camposample_audio. La voz base no cambia. - Vuelve a generar voz o a mezclar: Pasa el nuevo ID de voz en
speechConfig.voiceConfig.voicecuando llames agenerateContentostreamGenerateContent. Para definir mejor la voz, pasa el ID de voz nuevo como elbase_voicede otra solicitudcreate.
Antes de comenzar
-
Instala Google Cloud CLI.
-
Configura gcloud CLI para usar tu identidad federada.
Para obtener más información, consulta Accede a gcloud CLI con tu identidad federada.
-
Para inicializar gcloud CLI, ejecuta el siguiente comando:
gcloud init -
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 permisoresourcemanager.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_IDpor 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_IDpor el nombre de tu proyecto de Cloud de Confiance .
-
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.
-
Verifica que la facturación esté habilitada para tu proyecto de Cloud de Confiance .
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
-
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 :
-
Crea, enumera, obtén y borra voces, y genera voz:
Usuario de Agent Platform (
roles/aiplatform.user)
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 sertrue. Las voces remezcladas siempre se almacenan en tu proyecto. Las solicitudes que configuranbase_voiceconstore: falsefallan con un errorINVALID_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 devoice_...para una voz diseñada o remezclada. Si la voz no existe, la solicitud falla con un errorNOT_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 campodatacontiene el audio codificado en Base64, y el campomime_typenombra 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 verificarmime_typeantes 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
createde 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_voicede 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
createdevuelve un errorRESOURCE_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.inputsolicite 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_audioantes de realizar el siguiente cambio. - Usa la remezcla para los rasgos permanentes y
speech_metadata.stylepara 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 despeech_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.