Creare una voce personalizzata con la progettazione vocale

Puoi creare una voce personalizzata da una descrizione in linguaggio naturale utilizzando la funzionalità di progettazione della voce. Anziché scegliere una voce predefinita o registrare un audio di riferimento, crei una voce descrivendo l'età, il timbro vocale, l'accento e l'intonazione di base di un personaggio. L'API Voices archivia la voce nel tuo progetto e restituisce un ID voice_... riutilizzabile che passi nelle richieste di generazione della voce.

Le voci progettate funzionano sia con Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) sia con Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts).

Come funziona la progettazione vocale

  1. Crea una voce con prompt: chiama il metodo create dell'API Voices con voice.type impostato su VOICE_TYPE_PROMPTED e store impostato su true.
  2. Ricevi un ID voce e un campione: l'API Voices genera la voce, la memorizza nel tuo progetto e restituisce il suo ID (ad esempio, voice_abc123...) nel campo id e un campione della voce nel campo sample_audio.
  3. Genera parlato: passa l'ID voce in speechConfig.voiceConfig.voice quando chiami generateContent o streamGenerateContent.

Prima di iniziare

Completa i passaggi descritti in Prima di iniziare nella pagina di Gemini TTS. L'API Voices è disponibile nella località global tramite la versione dell'API v1beta1.

Crea una voce progettata

Imposta i seguenti campi nella richiesta:

  • store: deve essere true. Le voci progettate vengono sempre archiviate nel tuo progetto.
  • voice.type: VOICE_TYPE_PROMPTED.
  • voice.prompted.input: una descrizione della voce in linguaggio naturale.
  • voice.display_name, voice.gender, voice.language_code: metadati facoltativi per la voce.

Non impostare voice.model. Le richieste che impostano un modello insieme a store: true non vanno a buon fine e generano un errore INVALID_ARGUMENT.

La progettazione di una voce può richiedere diversi secondi. L'esempio Python imposta il timeout della richiesta su 60 secondi.

La risposta contiene i seguenti campi:

  • id: l'ID della nuova voce.
  • sample_audio: un esempio della voce. Il campo data contiene l'audio codificato in base64 e il campo mime_type ne indica la codifica. Ad esempio, audio/l16; rate=24000; channels=1 è un PCM a 16 bit senza intestazione a 24 kHz, mono.
  • usage: il numero di token utilizzati dalla richiesta. Per saperne di più, consulta i prezzi.

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

Se sample_audio.mime_type è audio/l16, il file voice_sample.pcm contiene audio PCM a 16 bit senza intestazione a 24 kHz, mono.

Per ascoltare la voce con il tuo testo, genera il parlato come mostrato nella sezione successiva.

Genera voce con una voce progettata

Passa l'ID voce 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

Sostituisci VOICE_ID con l'ID voce restituito dal metodo create.

Gestisci le voci memorizzate

Puoi elencare, recuperare ed eliminare le voci archiviate nel tuo progetto, incluse le voci progettate e le voci replicate archiviate. Il metodo list restituisce le voci memorizzate nel progetto, seguite dalle voci predefinite e della libreria di voci estesa. Per elencare solo le voci archiviate nel tuo progetto, imposta il filtro type su prompted e replicated, come negli esempi seguenti. Il metodo get restituisce anche l'esempio di una voce progettata nel campo 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

Limiti

  • Le voci memorizzate scadono un anno dopo l'ultimo utilizzo. La generazione di parlato con una voce riavvia questo periodo, quindi una voce che utilizzi regolarmente non scade. Elimina le voci che non ti servono più.
  • Le richieste di creazione della voce sono soggette a una quota per progetto e al minuto. Se lo superi, il metodo create restituisce un errore RESOURCE_EXHAUSTED. Attendi e riprova. Per saperne di più, consulta Quote e limiti di sistema.

Prezzi

La creazione di una voce progettata viene fatturata come token di input di testo e token di output audio alle tariffe di Gemini 3.8 Flash TTS. I token di output audio coprono il campione vocale generato dall'API Voices. Il campo usage nella risposta create riporta entrambi i conteggi. Ad esempio, la descrizione di una frase nell'esempio di creazione utilizza circa 220 token di input e circa 1100 token di output.

I metodi get, list e delete non vengono fatturati. Il parlato generato con una voce progettata viene fatturato in base alle tariffe del modello che chiami.

Per le tariffe dei token, consulta Prezzi di Gemini Enterprise.

Best practice per i prompt

  • Inserisci i tratti permanenti nella descrizione della voce: definisci età, genere, timbro, struttura vocale e accento regionale quando crei la voce, non in speech_metadata.style.
  • Utilizza speech_metadata.style per le emozioni situazionali: dopo aver creato la voce, utilizza valori style brevi, come "whispered urgently" o "cheerful and energetic", per indirizzare ogni turno senza modificare l'identità di chi parla.
  • Fornisci dettagli specifici e concisi: una descrizione chiara di una o due frasi, come "Una commentatrice sportiva energica e vivace di circa 30 anni con un leggero accento del Midwest", produce risultati più coerenti rispetto a un paragrafo lungo o contraddittorio.

Passaggi successivi