El diseño de voz te permite crear una personificación vocal persistente y completamente nueva a partir de una descripción en lenguaje natural con el extremo Voices de la API de Gemini (POST /v1beta/voices). En lugar de limitarte a voces prediseñadas o a grabar audio de referencia, puedes describir la edad, el timbre, el acento y la forma de hablar de un personaje, y recibir un ID de voice_... reutilizable que se guarda en tu proyecto.
La forma más rápida de diseñar, probar y realizar iteraciones en voces personalizadas es con el estudio interactivo Voice Design en Google AI Studio. Puedes generar arquetipos personalizados a partir de instrucciones de texto, probarlos con muestras de secuencias de comandos y copiar el ID de voice_... resultante directamente en el código de la aplicación.
Tanto Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) como Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) admiten el diseño de voz.
Crea una voz diseñada
Usa el SDK de GenAI de Google (google-genai 2.25.0 o posterior / @google/genai 2.24.0 o posterior) o la API de REST para crear una voz personalizada a partir de una descripción de texto. En el caso de las voces de "prompted", tanto voices.create (CreateVoice) como voices.get (GetVoice) devuelven un campo sample_audio de solo salida (mime_type: "audio/wav", data codificado en base64) para que puedas escuchar de inmediato la voz generada:
Python
import base64
from google import genai
client = genai.Client()
# 1. Design a custom voice persona from natural language
created_voice = client.voices.create(
store=True,
voice={
"model": "gemini-3.8-flash-tts",
"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."
)
},
},
)
print(f"Created voice ID: {created_voice.id}")
# Save the generated sample_audio preview (audio/wav) returned by CreateVoice
if created_voice.sample_audio and created_voice.sample_audio.data:
with open("voice_preview.wav", "wb") as f:
f.write(base64.b64decode(created_voice.sample_audio.data))
JavaScript
import * as fs from "node:fs";
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI();
// 1. Design a custom voice persona from natural language
const createdVoice = await ai.voices.create({
store: true,
voice: {
model: "gemini-3.8-flash-tts",
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.",
},
},
});
console.log(`Created voice ID: ${createdVoice.id}`);
// Save the generated sample_audio preview (audio/wav) returned by CreateVoice
if (createdVoice.sample_audio?.data) {
fs.writeFileSync(
"voice_preview.wav",
Buffer.from(createdVoice.sample_audio.data, "base64")
);
}
REST
curl "https://generativelanguage.googleapis.com/v1beta/voices" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"store": true,
"voice": {
"model": "gemini-3.8-flash-tts",
"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."
}
}
}' | tee created_voice.json | jq -r '.sample_audio.data' | base64 --decode > voice_preview.wav
Cómo funciona el diseño de voz
- Crea una voz guiada: Llama a
voices.create(POST /v1beta/voices) contype="prompted"ystore=True. - Recibe una vista previa persistente de
voice_idysample_audio: La API genera la identidad vocal, la almacena en tu proyecto y devuelve un ID permanente (por ejemplo,voice_abc123...) junto consample_audio(mime_type: "audio/wav",datacodificado en base64) que contiene el audio de vista previa generado para la voz. - Sintetiza voz: Pasa el
voice_iden cualquier lugar donde se acepte un nombre de voz en tus solicitudes de síntesis.
Sintetiza la voz con la voz que diseñaste
Una vez que hayas creado una voz, pasa su id (voice_...) a la API de Interactions para generar voz:
Python
import base64
from google import genai
client = genai.Client()
interaction = client.interactions.create(
model="gemini-3.8-flash-tts",
input=[{
"type": "user_input",
"content": [{
"type": "text",
"text": (
"Look out past the rings of Saturn. Those faint photons left"
" their source millions of years ago."
),
"annotations": [{
"type": "speech_metadata",
"style": "reflective and awe-inspired",
}],
}],
}],
response_format={"type": "audio"},
generation_config={
"speech_config": [
{"voice": created_voice.id},
]
},
)
with open("designed_voice.wav", "wb") as f:
f.write(base64.b64decode(interaction.output_audio.data))
JavaScript
import * as fs from "node:fs";
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI();
const interaction = await ai.interactions.create({
model: "gemini-3.8-flash-tts",
input: [{
type: "user_input",
content: [{
type: "text",
text: "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
annotations: [{
type: "speech_metadata",
style: "reflective and awe-inspired",
}],
}],
}],
response_format: { type: "audio" },
generation_config: {
speech_config: [
{ voice: createdVoice.id },
],
},
});
fs.writeFileSync("designed_voice.wav", Buffer.from(interaction.output_audio.data, "base64"));
REST
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-X POST \
-d '{
"model": "gemini-3.8-flash-tts",
"input": [{
"type": "user_input",
"content": [{
"type": "text",
"text": "Look out past the rings of Saturn. Those faint photons left their source millions of years ago.",
"annotations": [{
"type": "speech_metadata",
"style": "reflective and awe-inspired"
}]
}]
}],
"response_format": {"type": "audio"},
"generation_config": {
"speech_config": [
{"voice": "voice_YOUR_DESIGNED_VOICE_ID"}
]
}
}'
Administra tus voces
Puedes enumerar, filtrar, inspeccionar y borrar tus voces almacenadas en cualquier momento con la API de Voices (consulta Biblioteca de voces extendida y filtrado para ver todos los parámetros de filtro).
- Límites de almacenamiento y TTL: Las voces con estado (
store=True, compartidas entre las voces replicadas y las generadas a partir de instrucciones) tienen un límite de 200 voces por proyecto y un TTL de 1 año (tiempo de actividad). Disponibilidad de
sample_audio:voices.create()(CreateVoice) yvoices.get()(GetVoice) completansample_audio(mime_type: "audio/wav",datacodificado en base64) para las voces de"prompted". Para que la lista sea liviana,voices.list()(ListVoices) omitesample_audio(ysample_audiono se establece para las voces"replicated"y"prebuilt").
Python
from google import genai
client = genai.Client()
# List stored prompted voices in your project filtered by language
response = client.voices.list(
type_=["prompted"],
language_code=["en-US", "en-GB"],
)
for voice in response.voices or []:
print(voice.id, voice.display_name, voice.type)
# Retrieve a specific voice by ID
voice_details = client.voices.get(id=created_voice.id)
# Delete a stored custom voice
client.voices.delete(id=created_voice.id)
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI();
// List stored prompted voices in your project filtered by language
const response = await ai.voices.list({
type: ["prompted"],
language_code: ["en-US", "en-GB"],
});
for (const voice of response.voices ?? []) {
console.log(voice.id, voice.display_name, voice.type);
}
// Retrieve a specific voice by ID
const voiceDetails = await ai.voices.get(createdVoice.id);
// Delete a stored custom voice
await ai.voices.delete(createdVoice.id);
REST
# List stored prompted voices filtered by language
curl -G "https://generativelanguage.googleapis.com/v1beta/voices" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
--data-urlencode "type=prompted" \
--data-urlencode "language_code=en-US" \
--data-urlencode "language_code=en-GB"
# Retrieve a specific voice by ID
curl "https://generativelanguage.googleapis.com/v1beta/voices/voice_YOUR_DESIGNED_VOICE_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY"
# Delete a stored custom voice
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/voices/voice_YOUR_DESIGNED_VOICE_ID" \
-H "x-goog-api-key: $GEMINI_API_KEY"
Prácticas recomendadas para la creación de instrucciones para el diseño de voz
- Coloca rasgos vocales permanentes en el diseño de voz, no en
style: Define características inmutables, como la edad, el género, el timbre, la textura vocal y el acento regional, cuando crees la voz envoices.create. - Reserva
speech_metadata.stylepara la emoción situacional: Una vez que se cree tu voz personalizada, usa instruccionesstylecortas (por ejemplo,"whispered urgently"o"cheerful and energetic") para dirigir la actuación paso a paso sin alterar la identidad principal del orador. - Sé específico y conciso: Una descripción clara de 1 o 2 oraciones (como "Una locutora deportiva enérgica y nítida de unos 30 años con un ligero acento del Medio Oeste") produce resultados más limpios y coherentes que los párrafos contradictorios o demasiado largos.
¿Qué sigue?
- Obtén información para replicar la voz de un orador existente en Replicación de voz.
- Explora el diseño a nivel de turnos, las etiquetas intercaladas y el diálogo de varios oradores en la guía de Text-to-Speech.