Crea una voz personalizada con diseño de voz

Puedes crear una voz personalizada a partir de una descripción en lenguaje natural con la función de diseño de voz. En lugar de elegir una voz prediseñada o grabar un audio de referencia, creas una voz describiendo la edad, el timbre vocal, el acento y la forma de hablar de un personaje. La API de Voices almacena la voz en tu proyecto y devuelve un ID de voice_... reutilizable que pasas en las solicitudes de generación de voz.

Las voces diseñadas 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 el diseño de voz

  1. Crea una voz con instrucciones: Llama al método create de la API de Voices con voice.type establecido en VOICE_TYPE_PROMPTED y store establecido en true.
  2. Recibe un ID de voz y una muestra: La API de Voices genera la voz, la almacena 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.
  3. Genera voz: Pasa el ID de voz en speechConfig.voiceConfig.voice cuando llames a generateContent o streamGenerateContent.

Antes de comenzar

Completa los pasos de Antes de comenzar en la página de TTS de Gemini. La API de Voices está disponible en la ubicación global a través de la versión de la API v1beta1.

Crea una voz diseñada

Establece los siguientes campos en la solicitud:

  • store: Debe ser true. Las voces diseñadas siempre se almacenan en tu proyecto.
  • voice.type: VOICE_TYPE_PROMPTED.
  • voice.prompted.input: Es una descripción en lenguaje natural de la voz.
  • voice.display_name, voice.gender, voice.language_code: Metadatos opcionales para la voz.

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

Diseñar 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.
  • sample_audio: Es una muestra de la voz. 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.

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. 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("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.wav

De forma predeterminada, sample_audio.mime_type es audio/wav y el archivo voice_sample.wav es un archivo WAV completo. Si mime_type es audio/l16, el archivo contiene audio PCM de 16 bits sin encabezado a 24 kHz, mono, y necesita un encabezado WAV antes de que la mayoría de los reproductores puedan abrirlo.

Para escuchar la voz con tu propio texto, genera voz con ella, como se muestra en la siguiente sección. Para cambiar algunas características de la voz más adelante sin volver a describirla, remézclala con la remixación de voz.

Genera voz con una voz diseñada

Pasa el ID de voz en 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

Reemplaza VOICE_ID por el ID de voz que devolvió el método create.

Administra las voces almacenadas

Puedes enumerar, obtener y borrar las voces almacenadas en tu proyecto, incluidas las voces diseñadas, las voces remezcladas y las voces replicadas almacenadas. El método list devuelve las voces almacenadas en tu proyecto, seguidas de las voces precompiladas y de la Biblioteca de voces extendida. Para enumerar solo las voces almacenadas en tu proyecto, establece el filtro type en prompted y replicated, como se hace en los siguientes ejemplos. El tipo prompted incluye voces diseñadas y remezcladas. El método get también devuelve la muestra de una voz diseñada o remezclada en el 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

Límites

  • Las voces almacenadas vencen un año después de su último uso. Generar voz con una voz o usarla como la voz base de un remix reinicia este período, por lo que una voz que usas con regularidad no vence. Borra las voces que ya no necesites.
  • Las solicitudes de creación de voces están sujetas a una cuota por proyecto y por minuto. 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 creación de una voz diseñada se factura como tokens de entrada de texto y tokens de salida de audio según las tarifas de Gemini 3.8 Flash TTS. Los tokens de salida de audio abarcan la muestra de voz que genera la API de Voices. El campo usage en la respuesta create informa ambos recuentos. Por ejemplo, la descripción de una oración en la muestra de creación usa alrededor de 220 tokens de entrada y alrededor de 1,100 tokens de salida.

No se facturan los métodos get, list ni delete. La voz que generas con una voz diseñada 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

  • Coloca rasgos permanentes en la descripción de la voz: Define la edad, el género, el timbre, la textura vocal y el acento regional cuando crees la voz, no en speech_metadata.style.
  • Usa speech_metadata.style para la emoción situacional: Después de crear la voz, usa valores cortos de style, como "whispered urgently" o "cheerful and energetic", para dirigir cada turno sin cambiar la identidad del interlocutor.
  • Sé específico y conciso: Una descripción clara de una o dos oraciones, como "Una locutora deportiva enérgica y de voz clara de unos 30 años con un ligero acento del Medio Oeste", produce resultados más coherentes que un párrafo largo o contradictorio.

¿Qué sigue?