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
- Crea una voce con prompt: chiama il metodo
createdell'API Voices convoice.typeimpostato suVOICE_TYPE_PROMPTEDestoreimpostato sutrue. - 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 campoide un campione della voce nel camposample_audio. - Genera parlato: passa l'ID voce in
speechConfig.voiceConfig.voicequando chiamigenerateContentostreamGenerateContent.
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 esseretrue. 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 campodatacontiene l'audio codificato in base64 e il campomime_typene 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
createrestituisce un erroreRESOURCE_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.styleper le emozioni situazionali: dopo aver creato la voce, utilizza valoristylebrevi, 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
- Replica la voce di uno speaker esistente con la replica vocale.
- Scopri di più sullo stile a livello di turno, sui tag incorporati e sul dialogo con più relatori in Genera voce con Gemini TTS.