Mit der Funktion Stimmendesign können Sie eine benutzerdefinierte Stimme aus einer Beschreibung in natürlicher Sprache erstellen. Anstatt eine vordefinierte Stimme auszuwählen oder eine Referenzaudioaufnahme zu erstellen, erstellen Sie eine Stimme, indem Sie das Alter, die Klangfarbe, den Akzent und die grundlegende Vortragsweise einer Figur beschreiben. Die Voices API speichert die Stimme in Ihrem Projekt und gibt eine wiederverwendbare voice_...-ID zurück, die Sie in Anfragen zur Sprachgenerierung übergeben.
Entworfene Stimmen funktionieren sowohl mit Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) als auch mit Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts).
So funktioniert Voice Design
- Prompt-basierte Stimme erstellen: Rufen Sie die Voices API-Methode
createauf, wobeivoice.typeaufVOICE_TYPE_PROMPTEDundstoreauftruegesetzt ist. - Stimm-ID und Beispiel erhalten: Die Voices API generiert die Stimme, speichert sie in Ihrem Projekt und gibt ihre ID (z. B.
voice_abc123...) im Feldidund ein Beispiel der Stimme im Feldsample_audiozurück. - Sprache generieren: Übergeben Sie die Sprach-ID in
speechConfig.voiceConfig.voice, wenn SiegenerateContentoderstreamGenerateContentaufrufen.
Hinweis
Führen Sie die Schritte unter Vorbereitung auf der Gemini TTS-Seite aus. Die Voices API ist in der Region global über die API-Version v1beta1 verfügbar.
Designte Stimme erstellen
Legen Sie in der Anfrage die folgenden Felder fest:
store: Musstruesein. Entworfene Stimmen werden immer in Ihrem Projekt gespeichert.voice.type:VOICE_TYPE_PROMPTED.voice.prompted.input: Eine Beschreibung der Stimme in natürlicher Sprache.voice.display_name,voice.gender,voice.language_code: Optionale Metadaten für die Stimme.
Legen Sie voice.model nicht fest. Anfragen, bei denen ein Modell zusammen mit store: true festgelegt wird, schlagen mit dem Fehler INVALID_ARGUMENT fehl.
Das Erstellen einer Stimme kann einige Sekunden dauern. Im Python-Beispiel wird das Zeitlimit für die Anfrage auf 60 Sekunden festgelegt.
Die Antwort umfasst die folgenden Felder:
id: Die ID der neuen Stimme.sample_audio: Eine Probe der Stimme. Das Felddataenthält die Base64-codierten Audioinhalte und das Feldmime_typedie Codierung. Beispiel:audio/l16; rate=24000; channels=1ist 16-Bit-PCM ohne Header mit 24 kHz, Mono.usage: Die Anzahl der Tokens, die für die Anfrage verwendet wurden. Weitere Informationen finden Sie unter Preise.
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. Raw 16-bit PCM (audio/l16) needs a WAV header.
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.pcm
Wenn sample_audio.mime_type den Wert audio/l16 hat, enthält die Datei voice_sample.pcm 16-Bit-PCM-Audio ohne Header mit 24 kHz, Mono.
Wenn Sie die Stimme mit Ihrem eigenen Text hören möchten, generieren Sie Sprache damit, wie im nächsten Abschnitt beschrieben.
Sprache mit einer entworfenen Stimme generieren
Übergeben Sie die Sprach-ID in 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
Ersetzen Sie VOICE_ID durch die Sprach-ID, die von der Methode create zurückgegeben wurde.
Gespeicherte Stimmen verwalten
Sie können die in Ihrem Projekt gespeicherten Stimmen auflisten, abrufen und löschen, einschließlich entworfener Stimmen und gespeicherter replizierter Stimmen.
Die Methode list gibt die in Ihrem Projekt gespeicherten Stimmen zurück, gefolgt von den vordefinierten Stimmen und den Stimmen aus der erweiterten Stimmenbibliothek. Wenn Sie nur die in Ihrem Projekt gespeicherten Stimmen auflisten möchten, setzen Sie den Filter type auf prompted und replicated, wie in den folgenden Beispielen gezeigt. Die Methode get gibt auch das Beispiel einer erstellten Stimme im Feld sample_audio zurück.
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
Limits
- Gespeicherte Stimmen laufen ein Jahr nach ihrer letzten Verwendung ab. Wenn Sie Sprache mit einer Stimme generieren, wird dieser Zeitraum neu gestartet. Eine Stimme, die Sie regelmäßig verwenden, läuft also nicht ab. Löschen Sie Stimmen, die Sie nicht mehr benötigen.
- Für Anfragen zur Erstellung von Stimmen gilt ein Kontingent pro Projekt und Minute. Wenn Sie dieses Limit überschreiten, gibt die Methode
createden FehlerRESOURCE_EXHAUSTEDzurück. Warten Sie und versuchen Sie es dann noch einmal. Weitere Informationen finden Sie unter Kontingente und Systemlimits.
Preise
Das Erstellen einer Designstimme wird als Texteingabe-Tokens und Audioausgabe-Tokens zu den Gemini 3.8 Flash TTS-Preisen abgerechnet. Die Audioausgabetokens decken das Sprachbeispiel ab, das die Voices API generiert. Im Feld usage der Antwort create werden beide Werte angegeben. Die einzeilige Beschreibung im Beispiel zum Erstellen verwendet beispielsweise etwa 220 Eingabetokens und etwa 1.100 Ausgabetokens.
Die Methoden get, list und delete werden nicht in Rechnung gestellt. Sprache, die Sie mit einer entworfenen Stimme generieren, wird zu den Preisen des von Ihnen aufgerufenen Modells abgerechnet.
Informationen zu den Token-Preisen finden Sie unter Gemini Enterprise-Preise.
Best Practices für die Prompt-Erstellung
- Dauerhafte Merkmale in die Sprachbeschreibung aufnehmen: Definieren Sie Alter, Geschlecht, Klangfarbe, Stimmstruktur und regionalen Akzent, wenn Sie die Stimme erstellen, nicht in
speech_metadata.style. speech_metadata.stylefür situative Emotionen verwenden: Nachdem Sie die Stimme erstellt haben, können Sie kurzestyle-Werte wie"whispered urgently"oder"cheerful and energetic"verwenden, um jede Äußerung zu steuern, ohne die Identität des Sprechers zu ändern.- Seien Sie konkret und prägnant: Eine klare Beschreibung in ein oder zwei Sätzen, z. B. „Eine energische Sportkommentatorin in ihren 30ern mit einem leichten Akzent aus dem Mittleren Westen“, liefert konsistentere Ergebnisse als ein langer oder widersprüchlicher Absatz.
Nächste Schritte
- Mit der Stimmen-Replikation die Stimme eines vorhandenen Sprechers replizieren.
- Informationen zu turn-level-Styling, Inline-Tags und Dialogen mit mehreren Sprechern finden Sie unter Sprache mit Gemini TTS generieren.