Custom Voice mit Voice Design erstellen

Mit der Funktion Stimmendesign können Sie eine benutzerdefinierte Stimme aus einer Beschreibung in natürlicher Sprache erstellen. Anstatt eine voreingestellte Stimme auszuwählen oder Referenz-Audio aufzunehmen, erstellen Sie eine Stimme, indem Sie das Alter, die Klangfarbe, den Akzent und die grundlegende Sprechweise einer Figur beschreiben. In der Voices API wird die Stimme in Ihrem Projekt gespeichert und eine wiederverwendbare voice_...-ID zurückgegeben, die Sie in Anfragen zur Sprachsynthese übergeben.

Die entwickelten 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 die Sprachgestaltung

  1. Aufforderungsbasierte Stimme erstellen: Rufen Sie die Voices API-Methode create auf, wobei voice.type auf VOICE_TYPE_PROMPTED und store auf true gesetzt ist.
  2. Sprach-ID und ‑beispiel erhalten: Die Voices API generiert die Stimme, speichert sie in Ihrem Projekt und gibt ihre ID (z. B. voice_abc123...) im Feld id und ein Beispiel der Stimme im Feld sample_audio zurück.
  3. Sprache generieren: Übergeben Sie die Sprach-ID in speechConfig.voiceConfig.voice, wenn Sie generateContent oder streamGenerateContent aufrufen.

Hinweis

Führen Sie die Schritte unter Vorbereitung auf der Seite „Gemini TTS“ aus. Die Voices API ist in der Region global über die API-Version v1beta1 verfügbar.

Design-Stimme erstellen

Legen Sie in der Anfrage die folgenden Felder fest:

  • store: Muss true sein. 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, in 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 Anfragen auf 60 Sekunden festgelegt.

Die Antwort umfasst die folgenden Felder:

  • id: Die ID der neuen Stimme.
  • sample_audio: Eine Sprachprobe. Das Feld data enthält die base64-codierten Audioinhalte und im Feld mime_type wird die Codierung angegeben. audio/l16; rate=24000; channels=1 ist beispielsweise eine headerlose 16-Bit-PCM-Datei 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 gleich audio/l16 ist, enthält die Datei voice_sample.pcm headerloses 16‑Bit-PCM-Audio 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 bestimmten Stimme generieren

Übergeben Sie die Voice-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 der entwickelten Stimmen und der gespeicherten replizierten Stimmen. Die list-Methode gibt die in Ihrem Projekt gespeicherten Stimmen zurück, gefolgt von den integrierten Stimmen und den Stimmen aus der Extended Voice Library. Wenn Sie nur die in Ihrem Projekt gespeicherten Stimmen auflisten möchten, legen Sie den Filter type auf prompted und replicated fest, wie in den folgenden Beispielen. Die Methode get gibt auch das Beispiel einer entwickelten 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 Stimmerstellung gilt ein Kontingent pro Projekt und Minute. Wenn Sie das Limit überschreiten, gibt die create-Methode einen RESOURCE_EXHAUSTED-Fehler zurück. Warte ein wenig und versuche es dann noch einmal. Weitere Informationen finden Sie unter Kontingente und Systemlimits.

Preise

Das Erstellen einer benutzerdefinierten Stimme wird zu den Gemini 3.8 Flash TTS-Preisen als Text-Eingabetokens und Audioausgabetokens abgerechnet. Die Audioausgabetokens decken das Sprachbeispiel ab, das von der Voices API generiert wird. Im Feld usage der create-Antwort werden beide Werte angegeben. Die Einzeiler-Beschreibung im Beispiel erstellen verwendet beispielsweise etwa 220 Eingabetokens und etwa 1.100 Ausgabetokens.

Die Methoden get, list und delete werden nicht abgerechnet. Sprache, die Sie mit einer benutzerdefinierten Stimme generieren, wird zu den Preisen des Modells abgerechnet, das Sie aufrufen.

Informationen zu Token-Raten finden Sie unter Gemini Enterprise-Preise.

Best Practices für die Prompt-Erstellung

  • Dauerhafte Merkmale in die Beschreibung der Stimme aufnehmen: Definieren Sie Alter, Geschlecht, Klangfarbe, Stimmstruktur und regionalen Akzent beim Erstellen der Stimme und nicht in speech_metadata.style.
  • speech_metadata.style für situative Emotionen verwenden: Nachdem Sie die Stimme erstellt haben, verwenden Sie kurze style-Werte wie "whispered urgently" oder "cheerful and energetic", um die einzelnen Äußerungen zu steuern, ohne die Identität des Sprechers zu ändern.
  • Seien Sie spezifisch und prägnant: Eine klare Beschreibung in ein oder zwei Sätzen, z. B. „Eine dynamische Sportmoderatorin in den Dreißigern mit leichtem Akzent aus dem Mittleren Westen“, führt zu konsistenteren Ergebnissen als ein langer oder widersprüchlicher Absatz.

Nächste Schritte