Puoi creare una nuova voce personalizzata modificando una voce esistente con la funzionalità di remix della voce. Anziché descrivere una voce da zero, scegli una voce di base e descrivi le modifiche da apportare, ad esempio un'età, un tono, un'energia, un timbro o un accento diversi. L'API Voices archivia il risultato come nuova voce nel tuo progetto e restituisce un ID voice_... riutilizzabile che passi nelle richieste di generazione del parlato.
Puoi remixare le seguenti voci:
- Una voce predefinita, ad esempio
PuckoKore. - Una voce della raccolta di voci estesa.
- Una voce progettata o una voce remixata in precedenza archiviata nel progetto.
Le voci remixate 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 il remix della voce
Il remix della voce utilizza lo stesso metodo create dell'API Voices della progettazione della voce, con l'aggiunta del campo voice.prompted.base_voice:
- Scegli una voce di base e descrivi le modifiche: chiama il metodo
createdell'API Voices convoice.typeimpostato suVOICE_TYPE_PROMPTED,storeimpostato sutrue,voice.prompted.base_voiceimpostato sul nome o sull'ID di una voce esistente evoice.prompted.inputimpostato su una descrizione delle modifiche. - Ricevi un nuovo ID voce e un campione: l'API Voices applica le modifiche alla voce di base, memorizza il risultato come nuova voce nel progetto e restituisce il relativo ID (ad esempio,
voice_abc123...) nel campoide un campione della voce nel camposample_audio. La voce di base non cambia. - Genera di nuovo il parlato o il remix: passa il nuovo ID voce in
speechConfig.voiceConfig.voicequando chiamigenerateContentostreamGenerateContent. Per perfezionare ulteriormente la voce, passa il nuovo ID voce comebase_voicedi un'altra richiestacreate.
Prima di iniziare
-
Installa Google Cloud CLI.
-
Configura gcloud CLI per utilizzare la tua identità federata.
Per saperne di più, consulta Accedi a gcloud CLI con la tua identità federata.
-
Per inizializzare gcloud CLI, esegui questo comando:
gcloud init -
Crea o seleziona un progetto Cloud de Confiance .
Ruoli richiesti per selezionare o creare un progetto
- Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per cui ti è stato concesso un ruolo.
-
Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (
roles/resourcemanager.projectCreator), che contiene l'autorizzazioneresourcemanager.projects.create. Scopri come concedere i ruoli.
-
Crea un progetto Cloud de Confiance :
gcloud projects create PROJECT_ID
Sostituisci
PROJECT_IDcon un nome per il progetto Cloud de Confiance che stai creando. -
Seleziona il progetto Cloud de Confiance che hai creato:
gcloud config set project PROJECT_ID
Sostituisci
PROJECT_IDcon il nome del progetto Cloud de Confiance .
-
Se utilizzi un progetto esistente per questa guida, verifica di disporre delle autorizzazioni necessarie per completare la guida. Se hai creato un nuovo progetto, disponi già delle autorizzazioni necessarie.
-
Verifica che la fatturazione sia attivata per il tuo progetto Cloud de Confiance .
Abilita l'API Agent Platform, se non è già abilitata:
Ruoli richiesti per abilitare le API
Per abilitare le API, devi disporre dell'autorizzazione
serviceusage.services.enable. Se hai creato il progetto, probabilmente disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.gcloud services enable aiplatform.googleapis.com
-
Crea credenziali di autenticazione locali per il tuo account utente:
gcloud auth application-default login
Se viene restituito un errore di autenticazione, verifica di aver eseguito l'accesso a gcloud CLI con la tua identità federata.
Per utilizzare gli esempi di Python, installa la versione 2.33.0 o successiva dell'SDK Google Gen AI:
pip install --upgrade "google-genai>=2.33.0"
L'API Voices è disponibile nella località global tramite la versione dell'API v1beta1.
Ruoli obbligatori
Per ottenere le autorizzazioni necessarie per remixare le voci e generare parlato con queste, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo progetto Cloud de Confiance by S3NS :
-
Creare, elencare, recuperare ed eliminare voci e generare parlato:
Agent Platform User (
roles/aiplatform.user)
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Crea una voce remixata
Imposta i seguenti campi nella richiesta:
store: deve esseretrue. Le voci remixate vengono sempre memorizzate nel progetto. Le richieste che impostanobase_voiceconstore: falsenon vanno a buon fine e restituiscono un erroreINVALID_ARGUMENT.voice.type:VOICE_TYPE_PROMPTED.voice.prompted.base_voice: la voce di cui eseguire il remix. Utilizza il nome della voce per una voce predefinita (ad esempio,Puck), l'ID voce per una voce della libreria di voci estesa o l'IDvoice_...per una voce progettata o remixata. Se la voce non esiste, la richiesta non va a buon fine e viene visualizzato un erroreNOT_FOUND.voice.prompted.input: una descrizione in linguaggio naturale delle modifiche da apportare alla voce di base.voice.display_name,voice.gender,voice.language_code: metadati facoltativi per la nuova 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.
Il remix 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.prompted.base_voice: la voce di base che hai remixato.sample_audio: un campione della nuova voce. Il campodatacontiene l'audio codificato in base64 e il campomime_typene indica la codifica. Per impostazione predefinita, il campione è un file WAV completo (audio/wav) con un'intestazione RIFF: PCM a 16 bit, 24 kHz, mono. Alcune voci possono restituire PCM a 16 bit senza intestazione (audio/l16; rate=24000; channels=1), quindi controllamime_typeprima di salvare l'audio.usage: il numero di token utilizzati dalla richiesta. Per saperne di più, consulta i prezzi.
I seguenti esempi remixano la voce predefinita Puck:
Python
Installa
pip install --upgrade google-genai
Per saperne di più, consulta la documentazione di riferimento dell'SDK.
Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
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": "Older British Puck",
"prompted": {
"base_voice": "Puck",
"input": (
"Make the voice sound slightly older and more grounded, with a"
" warm British accent and measured audiobook narration pacing."
),
},
},
timeout=60,
)
print(f"Created voice ID: {voice.id}")
# Save the voice sample. The SDK returns sample_audio.data as a base64
# string. By default, it's a complete WAV file (audio/wav). For
# compatibility, add a WAV header if the sample is raw 16-bit PCM
# (audio/l16).
sample = base64.b64decode(voice.sample_audio.data)
if voice.sample_audio.mime_type.lower().startswith("audio/l16"):
with wave.open("remixed_voice_sample.wav", "wb") as wf:
wf.setnchannels(1)
wf.setsampwidth(2)
wf.setframerate(24000)
wf.writeframes(sample)
else:
with open("remixed_voice_sample.wav", "wb") as f:
f.write(sample)
REST
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
Metodo HTTP e URL:
POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices
Corpo JSON della richiesta:
{
"store": true,
"voice": {
"type": "VOICE_TYPE_PROMPTED",
"displayName": "Older British Puck",
"prompted": {
"baseVoice": "Puck",
"input": "Make the voice sound slightly older and more grounded, with a warm British accent and measured audiobook narration pacing."
}
}
}
Per inviare la richiesta, scegli una di queste opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices"
PowerShell
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente. Il campo sample_audio.data è troncato.
{
"id": "voice_7bd85ebf-761b-4969-8544-4ec60f06d124",
"prompted": {
"base_voice": "Puck"
},
"usage": {
"total_tokens": 578,
"total_input_tokens": 297,
"input_tokens_by_modality": [
{"modality": "text", "tokens": 38},
{"modality": "audio", "tokens": 259}
],
"total_output_tokens": 281,
"output_tokens_by_modality": [
{"modality": "audio", "tokens": 281}
]
},
"sample_audio": {
"mime_type": "audio/wav",
"data": "UklGRpTwAwBXQVZF..."
}
}
Per impostazione predefinita, sample_audio.mime_type è audio/wav e sample_audio.data contiene un file WAV completo codificato in Base64. Se
mime_type è audio/l16, i dati decodificati sono audio PCM a 16 bit senza intestazione a 24 kHz, mono, e richiedono un'intestazione WAV prima che la maggior parte dei player
possa aprirli.
Genera voce con una voce remixata
Passa l'ID voce in speechConfig.voiceConfig.voice, nello stesso modo in cui passi una voce progettata:
Python
Installa
pip install --upgrade google-genai
Per saperne di più, consulta la documentazione di riferimento dell'SDK.
Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
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": "Chapter One. The fog rolled quietly across the harbor at dawn.",
"speech_metadata": {"style": "calm and reflective"},
}],
}],
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("remixed_voice.wav", "wb") as f:
f.write(response.candidates[0].content.parts[0].inline_data.data)
REST
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
- VOICE_ID: l'ID voce restituito dal metodo
createdell'API Voices.
Metodo HTTP e URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent
Corpo JSON della richiesta:
{
"contents": [{
"role": "user",
"parts": [{
"text": "Chapter One. The fog rolled quietly across the harbor at dawn.",
"speechMetadata": {"style": "calm and reflective"}
}]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {"voice": "VOICE_ID"}
}
}
}
Per inviare la richiesta, scegli una di queste opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent"
PowerShell
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent" | Select-Object -Expand Content
La risposta contiene l'audio come file WAV completo con codifica base64 in candidates[0].content.parts[0].inlineData.data. Il campo data è troncato.
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"inlineData": {
"mimeType": "audio/wav",
"data": "UklGRhRlBABXQVZF..."
}
}
]
},
"finishReason": "STOP"
}
]
}
Nell'esempio Python, sostituisci PROJECT_ID con il tuo ID progetto Cloud de Confiance by S3NSe VOICE_ID con l'ID voce restituito dal metodo create.
Perfeziona una voce passo passo
Ogni voce remixata è una voce voice_... memorizzata, quindi puoi utilizzarla come voce di base di un altro remix. Questo workflow passo passo ti consente di modificare uno o due tratti alla volta e di ascoltare ogni risultato prima di apportare la modifica successiva. Puoi anche iniziare da una voce predefinita.
I seguenti esempi remixano una voce esistente progettata o remixata:
Python
Installa
pip install --upgrade google-genai
Per saperne di più, consulta la documentazione di riferimento dell'SDK.
Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
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",
"prompted": {
"base_voice": "BASE_VOICE_ID",
"input": (
"Keep the same speaker identity and accent, but make the"
" delivery calmer, softer, and slightly lower in pitch."
),
},
},
timeout=60,
)
print(f"Created voice ID: {voice.id}")
print(f"Remixed from: {voice.prompted.base_voice}")
REST
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_ID: l'ID progetto Cloud de Confiance by S3NS .
- BASE_VOICE_ID: l'ID
voice_...di una voce progettata o remixata nel progetto.
Metodo HTTP e URL:
POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices
Corpo JSON della richiesta:
{
"store": true,
"voice": {
"type": "VOICE_TYPE_PROMPTED",
"prompted": {
"baseVoice": "BASE_VOICE_ID",
"input": "Keep the same speaker identity and accent, but make the delivery calmer, softer, and slightly lower in pitch."
}
}
}
Per inviare la richiesta, scegli una di queste opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices"
PowerShell
Salva il corpo della richiesta in un file denominato request.json,
quindi esegui il comando seguente:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente. Il campo sample_audio.data è troncato.
{
"id": "voice_f70c942e-7d78-427d-8466-cae3cb9b0371",
"prompted": {
"base_voice": "voice_7bd85ebf-761b-4969-8544-4ec60f06d124"
},
"sample_audio": {
"mime_type": "audio/wav",
"data": "UklGRhT4AgBXQVZF..."
}
}
Nell'esempio Python, sostituisci BASE_VOICE_ID con l'ID voice_... di una voce progettata o remixata nel tuo progetto.
Gestisci le voci remixate
Le voci remixate vengono archiviate nel progetto con il tipo VOICE_TYPE_PROMPTED, lo stesso delle voci progettate. Per elencare, recuperare o eliminare le voci remixate, utilizza gli stessi metodi delle voci progettate. Per maggiori dettagli, vedi Gestisci le voci memorizzate.
Una voce remixata è indipendente dalla voce di base:
- Il remix non modifica mai la voce di base.
- L'eliminazione della voce di base non influisce sulle voci remixate a partire da questa.
Limiti
- Le voci memorizzate scadono un anno dopo l'ultimo utilizzo. La generazione di contenuti vocali con una voce o l'utilizzo di quest'ultima come
base_voicedi un remix riavvia questo periodo. Elimina le voci che non ti servono più. - Le richieste di remix vengono conteggiate ai fini della stessa quota di creazione della voce per progetto e al minuto della progettazione e della replica vocale. Se superi questo limite, il metodo
createrestituisce un erroreRESOURCE_EXHAUSTED. Attendi e riprova. Per saperne di più, consulta Quote e limiti di sistema.
Prezzi
Il remix di una voce viene fatturato alle tariffe di Gemini 3.8 Flash TTS per i seguenti token:
- Token di input di testo per la descrizione in
voice.prompted.input. - Token di input audio per l'audio della voce di base.
- Token di output audio per il campione vocale generato dall'API Voices.
Il campo usage nella risposta create indica ogni conteggio. Ad esempio, il remix nell'esempio di creazione utilizza circa 40 token di input di testo, circa 260 token di input audio e circa 280 token di output audio.
I metodi get, list e delete non vengono fatturati. Il parlato generato con una voce remixata 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
- Descrivi solo le modifiche: il modello mantiene il suono della voce di base, quindi descrivi solo i tratti da modificare, come età, timbro, tono, ritmo o energia. Non ripetere la descrizione completa della voce.
- Specifica esplicitamente una nuova lingua o un nuovo accento: un remix mantiene la lingua
e l'accento regionale della voce di base, a meno che
voice.prompted.inputnon ne richieda un altro. - Modifica uno o due tratti per passaggio: quando perfezioni una voce in diversi remix, modifica un piccolo insieme di tratti in ogni richiesta e ascolta l'
sample_audioprima di apportare la modifica successiva. - Usa il remix per i tratti permanenti e
speech_metadata.styleper ogni turno: usa il remix della voce per modificare la base di una voce, ad esempio l'età, l'accento, il tono o la persona. Utilizza valorispeech_metadata.stylebrevi, come"whispered urgently"o"excited", per indirizzare la consegna dei singoli turni.
La seguente tabella mostra alcuni esempi di richieste di remix:
| Obiettivo | base_voice |
prompted.input |
|---|---|---|
| Modifica l'età e il timbro | Puck |
Make the voice sound 20 years older with a deeper, slightly
gravelly baritone timbre while keeping the friendly warmth. |
| Cambia l'accento regionale | Kore |
Change the accent to Australian English while preserving the
clear, confident studio delivery. |
| Adattamento a un dominio | Una voce progettata (voice_...) |
Adapt this voice for late-night meditation narration: lower the
vocal projection, slow the pacing, and soften the tone. |
| Aumenta l'energia | Una voce remixata (voice_...) |
Increase vocal energy and projection so the speaker sounds like
an upbeat live event announcer. |
Passaggi successivi
- Crea una voce personalizzata da una descrizione testuale con il design della voce.
- Replica la voce di un interlocutore 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.