Créer une voix personnalisée avec la conception vocale

Vous pouvez créer une voix personnalisée à partir d'une description en langage naturel à l'aide de la fonctionnalité de conception de voix. Au lieu de choisir une voix prédéfinie ou d'enregistrer un fichier audio de référence, vous créez une voix en décrivant l'âge, le timbre vocal, l'accent et le débit de base d'un personnage. L'API Voices stocke la voix dans votre projet et renvoie un ID voice_... réutilisable que vous transmettez dans les requêtes de génération de voix.

Les voix conçues fonctionnent à la fois avec Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) et Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts).

Fonctionnement de la conception vocale

  1. Créer une voix guidée : appelez la méthode create de l'API Voices avec voice.type défini sur VOICE_TYPE_PROMPTED et store défini sur true.
  2. Recevoir un ID de voix et un échantillon : l'API Voices génère la voix, la stocke dans votre projet et renvoie son ID (par exemple, voice_abc123...) dans le champ id et un échantillon de la voix dans le champ sample_audio.
  3. Générer un discours : transmettez l'ID de la voix dans speechConfig.voiceConfig.voice lorsque vous appelez generateContent ou streamGenerateContent.

Avant de commencer

Suivez les étapes de la section Avant de commencer de la page Gemini TTS. L'API Voices est disponible dans l'emplacement global via la version d'API v1beta1.

Créer une voix conçue

Définissez les champs suivants dans la requête :

  • store : doit être défini sur true. Les voix conçues sont toujours stockées dans votre projet.
  • voice.type : VOICE_TYPE_PROMPTED.
  • voice.prompted.input : description en langage naturel de la voix.
  • voice.display_name, voice.gender, voice.language_code : métadonnées facultatives pour la voix.

Ne définissez pas voice.model. Les requêtes qui définissent un modèle avec store: true échouent avec une erreur INVALID_ARGUMENT.

La conception d'une voix peut prendre plusieurs secondes. L'exemple Python définit le délai avant expiration de la requête sur 60 secondes.

La réponse contient les champs suivants :

  • id : ID de la nouvelle voix.
  • sample_audio : échantillon de la voix. Le champ data contient l'audio encodé en base64, et le champ mime_type indique son encodage. Par défaut, l'échantillon est un fichier WAV complet (audio/wav) avec un en-tête RIFF : PCM 16 bits, 24 kHz, mono. Certaines voix peuvent renvoyer un PCM 16 bits sans en-tête (audio/l16; rate=24000; channels=1) à la place. Vérifiez donc mime_type avant d'enregistrer l'audio.
  • usage : nombre de jetons utilisés par la requête. Pour en savoir plus, reportez-vous à la page Tarifs.

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

Par défaut, sample_audio.mime_type est défini sur audio/wav et le fichier voice_sample.wav est un fichier WAV complet. Si mime_type est audio/l16, le fichier contient un fichier audio PCM 16 bits sans en-tête à 24 kHz, mono, et nécessite un en-tête WAV pour que la plupart des lecteurs puissent l'ouvrir.

Pour entendre la voix avec votre propre texte, générez un discours avec celle-ci, comme indiqué dans la section suivante. Pour modifier ultérieurement certaines caractéristiques de la voix sans la décrire à nouveau, remixez-la avec le remixage de voix.

Générer un discours avec une voix conçue

Transmettez l'ID de voix dans 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

Remplacez VOICE_ID par l'ID de voix renvoyé par la méthode create.

Gérer les voix stockées

Vous pouvez lister, obtenir et supprimer les voix stockées dans votre projet, y compris les voix conçues, les voix remixées et les voix répliquées stockées. La méthode list renvoie les voix stockées dans votre projet, suivies des voix prédéfinies et de la bibliothèque de voix étendue. Pour ne lister que les voix stockées dans votre projet, définissez le filtre type sur prompted et replicated, comme dans les exemples suivants. Le type prompted inclut à la fois les voix conçues et les voix remixées. La méthode get renvoie également l'échantillon d'une voix conçue ou remixée dans le champ 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

Limites

  • Les voix stockées expirent un an après leur dernière utilisation. La génération de voix ou l'utilisation d'une voix comme voix de base d'un remix redémarre cette période. Ainsi, une voix que vous utilisez régulièrement n'expire pas. Supprimez les voix dont vous n'avez plus besoin.
  • Les requêtes de création de voix sont soumises à un quota par projet et par minute. Si vous la dépassez, la méthode create renvoie une erreur RESOURCE_EXHAUSTED. Patientez, puis réessayez. Pour en savoir plus, consultez Quotas et limites du système.

Tarifs

La création d'une voix conçue est facturée en tant que jetons d'entrée de texte et jetons de sortie audio aux tarifs de Gemini 3.8 Flash TTS. Les jetons de sortie audio couvrent l'échantillon vocal généré par l'API Voices. Le champ usage de la réponse create indique les deux nombres. Par exemple, la description d'une phrase dans l'exemple de création utilise environ 220 jetons d'entrée et environ 1 100 jetons de sortie.

Les méthodes get, list et delete ne sont pas facturées. Le discours que vous générez avec une voix conçue est facturé aux tarifs du modèle que vous appelez.

Pour connaître les tarifs des jetons, consultez Tarifs de Gemini Enterprise.

Bonnes pratiques concernant les prompts

  • Indiquez les caractéristiques permanentes dans la description de la voix : définissez l'âge, le genre, le timbre, la texture vocale et l'accent régional lorsque vous créez la voix, et non dans speech_metadata.style.
  • Utilisez speech_metadata.style pour les émotions situationnelles : après avoir créé la voix, utilisez des valeurs style courtes, telles que "whispered urgently" ou "cheerful and energetic", pour diriger chaque tour sans modifier l'identité du locuteur.
  • Soyez précis et concis : une description claire d'une ou deux phrases, telle que "Une commentatrice sportive énergique d'une trentaine d'années, avec un léger accent du Midwest", produit des résultats plus cohérents qu'un paragraphe long ou contradictoire.

Étapes suivantes