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
- Créer une voix guidée : appelez la méthode
createde l'API Voices avecvoice.typedéfini surVOICE_TYPE_PROMPTEDetstoredéfini surtrue. - 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 champidet un échantillon de la voix dans le champsample_audio. - Générer un discours : transmettez l'ID de la voix dans
speechConfig.voiceConfig.voicelorsque vous appelezgenerateContentoustreamGenerateContent.
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 surtrue. 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 champdatacontient l'audio encodé en base64, et le champmime_typeindique 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 doncmime_typeavant 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
createrenvoie une erreurRESOURCE_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.stylepour les émotions situationnelles : après avoir créé la voix, utilisez des valeursstylecourtes, 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
- Modifiez une voix conçue ou prédéfinie avec le remixage de voix.
- Répliquez la voix d'un locuteur existant avec la réplication vocale.
- Pour en savoir plus sur le style au niveau du tour de parole, les balises intégrées et les dialogues à plusieurs locuteurs, consultez Générer des voix avec Gemini TTS.