Replicar voces

Puedes reproducir la voz, el tono, la cadencia y el timbre de un interlocutor a partir de una muestra de audio breve con la función de replicación de voz. 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 la replicación de voz.

Para replicar una voz, debes enviar una grabación de referencia del interlocutor (source_audio) y una grabación del mismo interlocutor leyendo una declaración de consentimiento (consent_audio) a la API de Voices. El servicio verifica el consentimiento y devuelve un identificador para la voz replicada. Luego, pasas ese identificador en speechConfig.voiceConfig.voice en solicitudes generateContent o streamGenerateContent, sin volver a subir el audio.

Modos de almacenamiento

Cuando creas una voz replicada, el campo store selecciona uno de los dos modos de almacenamiento:

• Voz almacenada (store: true): Google almacena la voz replicada en tu proyecto y devuelve un ID de voz (voice_...) en el campo id. Puedes enumerar, obtener y borrar las voces almacenadas con la API de Voices.
• Clave de replicación de voz (store: false): Google no almacena la voz replicada. El servicio devuelve una clave de replicación de voz encriptada (voicekey_...) en el campo key, y tu aplicación almacena la clave. Usa este modo si tu carga de trabajo requiere que Google no conserve los perfiles de voz.

Generar voz con una voz almacenada reinicia su período de retención de un año, por lo que una voz que usas con regularidad no vence. Una solicitud que usa una clave de replicación de voz vencida falla con un error INVALID_ARGUMENT, y una solicitud que usa una voz almacenada borrada o vencida falla con un error NOT_FOUND. Para seguir usando una voz replicada, vuelve a crearla antes de que venza.

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 de v1beta1.

Requisitos de audio y consentimiento

Cada solicitud para crear una voz replicada necesita dos grabaciones de la misma persona adulta:

• Audio de referencia (source_audio): De 10 a 30 segundos de voz limpia y natural del interlocutor cuya voz quieres replicar. Por lo general, las muestras más largas producen mejores resultados.

• Audio de consentimiento (consent_audio): Es una grabación del mismo interlocutor leyendo la declaración de consentimiento para su idioma palabra por palabra. Para conocer las declaraciones, consulta Idiomas y declaraciones de consentimiento admitidos. En inglés, la afirmación es la siguiente:

  "Soy el propietario de esta voz y di mi consentimiento para que se cree un modelo sintético de mi voz a través del uso de Cloud de Confiance by S3NS".

Ambas grabaciones deben ser archivos WAV con PCM lineal de 16 bits con formato little-endian, mono, a 24 kHz.

Si la grabación del consentimiento no coincide con la declaración de consentimiento o el audio no cumple con los lineamientos de uso, la solicitud create falla con un error INVALID_ARGUMENT que describe el problema.

Crea una voz replicada almacenada

Establece los siguientes campos en la solicitud:

• store: true.
• voice.type: VOICE_TYPE_REPLICATED.
• voice.display_name: Opcional Es un nombre para la voz.
• voice.replicated.source_audio y voice.replicated.consent_audio: Son las grabaciones de referencia y consentimiento codificadas en Base64, cada una con mime_type configurado como audio/wav.

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

La respuesta devuelve el ID de voz en el campo id.

import base64

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

with open("SOURCE_AUDIO_PATH", "rb") as f:
    source_b64 = base64.b64encode(f.read()).decode("utf-8")

with open("CONSENT_AUDIO_PATH", "rb") as f:
    consent_b64 = base64.b64encode(f.read()).decode("utf-8")

replicated_voice = client.voices.create(
    store=True,
    voice={
        "type": "VOICE_TYPE_REPLICATED",
        "display_name": "Custom replicated speaker",
        "replicated": {
            "source_audio": {"mime_type": "audio/wav", "data": source_b64},
            "consent_audio": {"mime_type": "audio/wav", "data": consent_b64},
        },
    },
    timeout=60,
)

# The voice ID starts with "voice_".
print(f"Created voice ID: {replicated_voice.id}")

SOURCE_B64=$(base64 -w 0 SOURCE_AUDIO_PATH)
CONSENT_B64=$(base64 -w 0 CONSENT_AUDIO_PATH)

cat > request.json <<EOF
{
  "store": true,
  "voice": {
    "type": "VOICE_TYPE_REPLICATED",
    "displayName": "Custom replicated speaker",
    "replicated": {
      "sourceAudio": {"mimeType": "audio/wav", "data": "${SOURCE_B64}"},
      "consentAudio": {"mimeType": "audio/wav", "data": "${CONSENT_B64}"}
    }
  }
}
EOF

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 @request.json | jq -r '.id'

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto de Cloud de Confiance by S3NS .
• SOURCE_AUDIO_PATH: Es la ruta de acceso al archivo WAV de referencia.
• CONSENT_AUDIO_PATH: Es la ruta de acceso al archivo WAV de consentimiento.

Para enumerar, obtener o borrar voces replicadas almacenadas, usa los mismos métodos que para las voces diseñadas. Para obtener más información, consulta Administra las voces almacenadas.

Crea una clave de replicación de voz

Establece los siguientes campos en la solicitud:

• store: false.
• voice.type: VOICE_TYPE_REPLICATED.
• voice.model: Obligatorio. Es el modelo de Gemini 3.8 TTS con el que se creará la clave, por ejemplo, gemini-3.8-flash-tts. La clave funciona con ambos modelos de Gemini 3.8 TTS.
• voice.replicated.source_audio y voice.replicated.consent_audio: Son las grabaciones de referencia y consentimiento codificadas en Base64, cada una con mime_type configurado como audio/wav.

La respuesta devuelve la clave de replicación de voz en el campo key.

import base64

from google import genai

client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")

with open("SOURCE_AUDIO_PATH", "rb") as f:
    source_b64 = base64.b64encode(f.read()).decode("utf-8")

with open("CONSENT_AUDIO_PATH", "rb") as f:
    consent_b64 = base64.b64encode(f.read()).decode("utf-8")

replicated_voice = client.voices.create(
    store=False,
    voice={
        "model": "gemini-3.8-flash-tts",
        "type": "VOICE_TYPE_REPLICATED",
        "replicated": {
            "source_audio": {"mime_type": "audio/wav", "data": source_b64},
            "consent_audio": {"mime_type": "audio/wav", "data": consent_b64},
        },
    },
    timeout=60,
)

# Store the key in your application. It starts with "voicekey_".
voice_key = replicated_voice.key

SOURCE_B64=$(base64 -w 0 SOURCE_AUDIO_PATH)
CONSENT_B64=$(base64 -w 0 CONSENT_AUDIO_PATH)

cat > request.json <<EOF
{
  "store": false,
  "voice": {
    "model": "gemini-3.8-flash-tts",
    "type": "VOICE_TYPE_REPLICATED",
    "replicated": {
      "sourceAudio": {"mimeType": "audio/wav", "data": "${SOURCE_B64}"},
      "consentAudio": {"mimeType": "audio/wav", "data": "${CONSENT_B64}"}
    }
  }
}
EOF

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 @request.json | jq -r '.key'

Genera voz con una voz replicada

Pasa el ID de voz o la clave de replicación de voz en speechConfig.voiceConfig.voice:

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": "Hello! This audio was generated with a replicated voice.",
            "speech_metadata": {"style": "warm and conversational"},
        }],
    }],
    config={
        "response_modalities": ["AUDIO"],
        "speech_config": {"voice_config": {"voice": "VOICE"}},
    },
)

# The SDK has already decoded the base64 audio, so inline_data.data is a
# complete WAV file by default.
with open("replicated_voice.wav", "wb") as f:
    f.write(response.candidates[0].content.parts[0].inline_data.data)

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": "Hello! This audio was generated with a replicated voice.",
        "speechMetadata": {"style": "warm and conversational"}
      }]
    }],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "voiceConfig": {"voice": "VOICE"}
      }
    }
  }' | jq -r '.candidates[0].content.parts[0].inlineData.data' | base64 --decode > replicated_voice.wav

Reemplaza VOICE por el ID de voz (voice_...) o la clave de replicación de voz (voicekey_...) que devolvió el método create.

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 muestra un error RESOURCE_EXHAUSTED. Para obtener más información, consulta Cuotas y límites del sistema.

Idiomas y declaraciones de consentimiento admitidos

La API de Voices verifica el consentimiento comparando la transcripción de consent_audio con la declaración de consentimiento. El orador debe leer la declaración en su idioma palabra por palabra:

Prácticas recomendadas

• Graba en un entorno tranquilo: Minimiza el eco, el ruido de fondo, la música y las voces superpuestas. La calidad del resultado depende de la calidad de source_audio.
• Haz coincidir las condiciones de grabación: Graba source_audio y consent_audio con el mismo micrófono en la misma sala para que la verificación de la bocina se realice correctamente.
• Convierte al formato requerido: Vuelve a muestrear las grabaciones a 24 kHz, mono, PCM WAV de 16 bits antes de codificarlas.
• Planifica la renovación: Las claves de replicación de voz son válidas durante siete días y las voces almacenadas vencen un año después de su último uso. Conserva las grabaciones de origen y de consentimiento, o un proceso para recopilarlas, de modo que puedas volver a crear la voz antes de que venza.

¿Qué sigue?

• Crea una voz personalizada a partir de una descripción de texto con Diseño 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.