Creare una voce personalizzata con la progettazione vocale

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

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 della voce

  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 relativo ID (ad esempio, voice_abc123...) nel campo id e un campione della voce nel campo sample_audio.
  3. Genera discorso: passa l'ID voce in speechConfig.voiceConfig.voice quando chiami generateContent o streamGenerateContent.

Prima di iniziare

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

Creare una voce progettata

Imposta i seguenti campi nella richiesta:

  • store: deve essere true. Le voci create vengono sempre archiviate nel tuo progetto.
  • voice.type: VOICE_TYPE_PROMPTED.
  • voice.prompted.input: una descrizione in linguaggio naturale della voce.
  • 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 restituiscono 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 campione della voce. Il campo data contiene l'audio codificato in base64, mentre il campo mime_type ne indica la codifica. Ad esempio, audio/l16; rate=24000; channels=1 è PCM a 16 bit senza intestazione a 24 kHz, mono.

  • usage: Il numero di token utilizzati dalla richiesta. Per saperne di più, consulta la sezione 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 la sintesi vocale come mostrato nella sezione successiva.

Generare la 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.

Gestire le voci memorizzate

Puoi elencare, recuperare ed eliminare le voci memorizzate nel progetto, incluse le voci progettate e le voci replicate memorizzate. Il metodo list restituisce le voci memorizzate nel progetto, seguite dalle voci predefinite e della libreria di voci estese. Per elencare solo le voci archiviate nel tuo progetto, imposta il filtro type su prompted e replicated, come mostrato negli esempi seguenti. Il metodo get restituisce anche il campione 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 un discorso con una voce riavvia questo periodo, quindi una voce che usi regolarmente non scade. Elimina le voci che non ti servono più.
  • Le richieste di creazione di voci sono soggette a una quota per progetto 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 uscita audio alle tariffe TTS di Gemini 3.8 Flash. I token di uscita audio coprono il campione vocale generato dall'API Voices. Il campo usage nella risposta create registra entrambi i conteggi. Ad esempio, la descrizione di una frase in create sample utilizza circa 220 token di input e circa 1100 token di output.

I metodi get, list e delete non vengono fatturati. La sintesi vocale che generi con una voce progettata viene fatturata 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 l'emozione situazionale: dopo aver creato la voce, utilizza valori style brevi, ad esempio "whispered urgently" o "cheerful and energetic", per dirigere ogni turno senza modificare l'identità dell'oratore.
  • Sii specifico e conciso: una descrizione chiara di una o due frasi, ad esempio "Una telecronista sportiva energica e frizzante sui 30 anni con un leggero accento del Midwest", produce risultati più coerenti rispetto a un paragrafo lungo o contraddittorio.

Passaggi successivi