Generazione di sintesi vocale (TTS)

L'API Gemini può trasformare l'input di testo in audio con uno o più parlanti utilizzando le funzionalità di generazione di sintesi vocale (TTS) di Gemini. La generazione di sintesi vocale è controllabile, il che significa che puoi combinare i metadati strutturati del turno (speech_metadata) e i tag vocali incorporati per guidare lo stile, l'accento, il ritmo e il tono dell'audio.

La funzionalità TTS è diversa dalla generazione di parlato fornita tramite l'API Live, progettata per audio interattivo e non strutturato e input e output multimodali. Mentre l'API Live eccelle in contesti conversazionali dinamici, la sintesi vocale tramite l'API Gemini è pensata per scenari che richiedono una recitazione esatta del testo con un controllo preciso su stile e suono, come la generazione di podcast o audiolibri.

Questa guida mostra come generare audio con una o più voci dal testo utilizzando Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) e Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts).

Prima di iniziare

Assicurati di utilizzare un modello Gemini TTS elencato nella sezione Modelli supportati ed esegui l'upgrade all'SDK Google GenAI più recente (google-genai >= 2.25.0 per Python o @google/genai >= 2.24.0 per JavaScript/TypeScript) o utilizza l'API REST. Per risultati ottimali, consulta la sezione Quando utilizzare un modello per selezionare il modello migliore per il tuo carico di lavoro.

Potresti trovare utile testare i modelli Gemini TTS in AI Studio prima di iniziare a creare.

TTS con un solo speaker

Per convertire il testo in audio con un singolo interlocutore con i modelli Gemini 3.8 TTS, passa la trascrizione letterale in input, allega lo stile a livello di turno utilizzando un'annotazione speech_metadata e configura la voce in generation_config.speech_config. Puoi scegliere una voce tra le opzioni vocali predefinite, la libreria vocale estesa (GET /v1beta/voices), un ID progettazione vocale personalizzato (voice_...) o un ID replica vocale (voice_... o voicekey_... stateless facoltativo).

Questo esempio salva l'audio di output WAV predefinito (audio/wav) del modello direttamente in un file:

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))

import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
   });

   const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
   fs.writeFileSync('out.wav', audioBuffer);
}
await main();

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }' | jq -r '[.steps[] | select(.type=="model_output") | .content[] | select(.type=="audio")] | last | .data' | base64 --decode > out.wav

Negli SDK Python e SDK JavaScript, puoi recuperare i dati audio generati utilizzando la proprietà di convenienza interaction.output_audio, che restituisce l'ultimo blocco audio generato (nelle risposte JSON REST non elaborate, l'audio con codifica base64 è archiviato in steps[].content[].data). Per informazioni dettagliate sulle proprietà di convenienza, consulta la panoramica delle interazioni.

TTS con più interlocutori

Per i dialoghi con più interlocutori, configura due interlocutori in speech_config.speakers e passa ogni turno come elemento di testo separato con un'annotazione speech_metadata che specifica speaker e style facoltativo a livello di turno. Tieni presente che speech_config accetta un array ([{"voice": "..."}]) per la generazione con un singolo speaker e un oggetto ({"speakers": [...]}) per la generazione con più speaker:

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [
            {
                "type": "text",
                "text": "How's it going today Jane?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Joe",
                    "style": "cheerful and friendly",
                }],
            },
            {
                "type": "text",
                "text": "Not too bad, how about you? Ready to test these new voices?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Jane",
                    "style": "calm and relaxed",
                }],
            },
        ],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": {
            "speakers": [
                {"speaker": "Joe", "voice": "Puck"},
                {"speaker": "Jane", "voice": "Kore"},
            ],
        }
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))

import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [
            {
               type: 'text',
               text: "How's it going today Jane?",
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Joe',
                  style: 'cheerful and friendly',
               }],
            },
            {
               type: 'text',
               text: 'Not too bad, how about you? Ready to test these new voices?',
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Jane',
                  style: 'calm and relaxed',
               }],
            },
         ],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: {
            speakers: [
               { speaker: 'Joe', voice: 'Puck' },
               { speaker: 'Jane', voice: 'Kore' },
            ],
         },
      },
   });

   const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
   fs.writeFileSync('out.wav', audioBuffer);
}

await main();

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "How'\''s it going today Jane?",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Joe",
            "style": "cheerful and friendly"
          }]
        },
        {
          "type": "text",
          "text": "Not too bad, how about you? Ready to test these new voices?",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Jane",
            "style": "calm and relaxed"
          }]
        }
      ]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": {
        "mode": "conversational",
        "speakers": [
          { "speaker": "Joe", "voice": "Puck" },
          { "speaker": "Jane", "voice": "Kore" }
        ]
      }
    }
  }'

Controlla lo stile del parlato con metadati e tag

Gemini 3.8 TTS tratta il campo text rigorosamente come una trascrizione letterale. Per controllare la consegna senza che le indicazioni di scena vengano lette ad alta voce, suddividi le istruzioni per ambito:

• Pronuncia sostenuta a livello di turno (speech_metadata.style): inserisci emozioni, stile di pronuncia, prosodia, ritmo e volume che si applicano a un intero turno nel campo style (ad esempio, "style": "whispered urgently", "style": "out of breath" o "style": "warm and enthusiastic").
• Eventi puntuali (tag in linea): inserisci brevi pause o interruzioni vocali non verbali direttamente all'interno della trascrizione utilizzando le parentesi angolari (ad esempio, "Wait... <short pause> did you hear that? <sigh>" o "Excuse me <cough> as I was saying...").

Consulta la guida ai prompt per le best practice complete.

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [
            {
                "type": "text",
                "text": "Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Dr. Anya",
                    "style": "whispered urgently",
                }],
            },
            {
                "type": "text",
                "text": "<gasp> No way! <laugh> We've been searching for this species all season!",
                "annotations": [{
                    "type": "speech_metadata",
                    "speaker": "Liam",
                    "style": "warm and enthusiastic",
                }],
            },
        ],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": {
            "speakers": [
                {"speaker": "Dr. Anya", "voice": "Kore"},
                {"speaker": "Liam", "voice": "Puck"},
            ],
        }
    },
)

with open("out.wav", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))

import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [
            {
               type: 'text',
               text: 'Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?',
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Dr. Anya',
                  style: 'whispered urgently',
               }],
            },
            {
               type: 'text',
               text: "<gasp> No way! <laugh> We've been searching for this species all season!",
               annotations: [{
                  type: 'speech_metadata',
                  speaker: 'Liam',
                  style: 'warm and enthusiastic',
               }],
            },
         ],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: {
            speakers: [
               { speaker: 'Dr. Anya', voice: 'Kore' },
               { speaker: 'Liam', voice: 'Puck' },
            ],
         },
      },
   });

   if (interaction.output_audio?.data) {
      const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
      fs.writeFileSync('out.wav', audioBuffer);
   }
}

await main();

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Wait... <short pause> look under that fallen log! Is that a blue-spotted salamander?",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Dr. Anya",
            "style": "whispered urgently"
          }]
        },
        {
          "type": "text",
          "text": "<gasp> No way! <laugh> We'\''ve been searching for this species all season!",
          "annotations": [{
            "type": "speech_metadata",
            "speaker": "Liam",
            "style": "warm and enthusiastic"
          }]
        }
      ]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": {
        "speakers": [
          { "speaker": "Dr. Anya", "voice": "Kore" },
          { "speaker": "Liam", "voice": "Puck" }
        ]
      }
    }
  }'

Generazione di voce in streaming

Puoi riprodurre in streaming l'audio generato mentre viene sintetizzato impostando stream: true. A differenza delle richieste unarie (che restituiscono un file WAV completo con un'intestazione RIFF), per impostazione predefinita le richieste di streaming restituiscono blocchi PCM lineari little-endian con segno a 16 bit non elaborati senza intestazione (audio/l16, 24 kHz, mono), in modo che i blocchi audio possano essere riprodotti o concatenati continuamente senza intestazioni del container.

import base64
from google import genai

client = genai.Client()

stream = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={"type": "audio"},
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
    stream=True,
)

for event in stream:
    if event.event_type == "step.delta":
        if event.delta.type == "audio":
            audio_data = base64.b64decode(event.delta.data)
            # Process the audio chunk (e.g. play it or write to a file)

import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const stream = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: { type: 'audio' },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
      stream: true,
   });

   for await (const event of stream) {
      if (event.event_type === 'step.delta') {
         if (event.delta.type === 'audio') {
            const audioBuffer = Buffer.from(event.delta.data, 'base64');
            // Process the audio buffer
         }
      }
   }
}
await main();

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  --no-buffer \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    },
    "stream": true
  }'

Formati di output audio

I modelli TTS Gemini 3.8 utilizzano formati audio predefiniti diversi a seconda che la richiesta sia unaria o in streaming:

• Richieste unarie (stream=False): restituiscono l'audio WAV (audio/wav) completo con un'intestazione RIFF standard (24 kHz, mono, PCM little-endian con segno a 16 bit). Puoi salvare i byte audio decodificati direttamente in un file .wav senza anteporre manualmente un'intestazione WAV.
• Richieste di streaming (stream=True): restituiscono blocchi PCM lineare non elaborato senza intestazione (audio/l16) (24 kHz, mono, PCM little-endian con segno a 16 bit) per impostazione predefinita, in modo che i blocchi possano essere trasmessi in streaming o concatenati continuamente senza intestazioni del container su ogni blocco.

Per richiedere una codifica audio o una frequenza di campionamento diversa, configura mime_type e sample_rate facoltativo all'interno di response_format:

Puoi anche specificare sample_rate in hertz (ad esempio 24000, 16000 o 8000).

import base64
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash-tts",
    input=[{
        "type": "user_input",
        "content": [{
            "type": "text",
            "text": "Have a wonderful day!",
            "annotations": [{
                "type": "speech_metadata",
                "style": "cheerful and friendly",
            }],
        }],
    }],
    response_format={
        "type": "audio",
        "mime_type": "audio/l16",  # "audio/wav" (default), "audio/l16", "audio/mulaw", or "audio/alaw"
        "sample_rate": 24000,
    },
    generation_config={
        "speech_config": [
            {"voice": "Kore"},
        ]
    },
)

with open("out.pcm", "wb") as f:
    f.write(base64.b64decode(interaction.output_audio.data))

import * as fs from 'node:fs';
import {GoogleGenAI} from '@google/genai';

async function main() {
   const client = new GoogleGenAI({});

   const interaction = await client.interactions.create({
      model: 'gemini-3.8-flash-tts',
      input: [{
         type: 'user_input',
         content: [{
            type: 'text',
            text: 'Have a wonderful day!',
            annotations: [{
               type: 'speech_metadata',
               style: 'cheerful and friendly',
            }],
         }],
      }],
      response_format: {
         type: 'audio',
         mime_type: 'audio/l16', // 'audio/wav' (default), 'audio/l16', 'audio/mulaw', or 'audio/alaw'
         sample_rate: 24000,
      },
      generation_config: {
         speech_config: [
            { voice: 'Kore' },
         ],
      },
   });

   const audioBuffer = Buffer.from(interaction.output_audio.data, 'base64');
   fs.writeFileSync('out.pcm', audioBuffer);
}
await main();

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash-tts",
    "input": [{
      "type": "user_input",
      "content": [{
        "type": "text",
        "text": "Have a wonderful day!",
        "annotations": [{
          "type": "speech_metadata",
          "style": "cheerful and friendly"
        }]
      }]
    }],
    "response_format": {
      "type": "audio",
      "mime_type": "audio/l16",
      "sample_rate": 24000
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }'

Opzioni vocali

Gemini 3.8 TTS supporta quattro modi per selezionare o creare voci:

1. Voci di studio predefinite:30 voci selezionate elencate nella tabella seguente.
2. Libreria di voci estesa:centinaia di voci aggiuntive in diverse lingue, accenti e archetipi di personaggi accessibili tramite client.voices.list() (GET /v1beta/voices).
3. Voice design: genera un'identità vocale personalizzata da una descrizione in linguaggio naturale in Google AI Studio o utilizzando POST /v1beta/voices (type="prompted", che restituisce un ID voice_... persistente e un'anteprima WAV sample_audio in CreateVoice e GetVoice).
4. Replica vocale: replica la voce di un interlocutore dall'audio di riferimento e di consenso in Google AI Studio o utilizzando POST /v1beta/voices (type="replicated", store=True persistente per impostazione predefinita o store=False stateless facoltativo).

Limiti e TTL della voce personalizzata

* Estensione del TTL: la finestra di conservazione di 1 anno viene reimpostata ogni volta che la voce viene utilizzata attivamente (sintetizzando il parlato con la voce o utilizzandola come voce di base per il remix). Le voci senza attività per 1 anno vengono eliminate automaticamente.

Voci predefinite

Libreria di voci estesa e filtri

Oltre alle 30 voci di Studio presenti nella tabella precedente, la libreria di voci estesa offre centinaia di voci aggiuntive in diverse lingue, accenti regionali, personaggi e domini. Puoi sfogliare, filtrare e provare l'intera libreria di voci in modo interattivo in Google AI Studio oppure interrogarla in modo programmatico utilizzando client.voices.list() (GET /v1beta/voices, utilizzando google-genai 2.25.0+ / @google/genai 2.24.0+).

ListVoices restituisce le voci personalizzate archiviate (ordinate dalla più recente alla più vecchia), seguite dalle voci del catalogo predefinite che corrispondono ai criteri di filtro. Quando vengono passati più valori per un filtro elenco, vengono restituite le voci corrispondenti a qualsiasi valore in quel filtro (OR), mentre i parametri di filtro distinti vengono combinati con AND:

from google import genai

client = genai.Client()

# Filter the Voice Library by language, gender, pitch, domain context, and keyword
response = client.voices.list(
    language_code=["en-US", "en-GB"],
    gender=["female"],
    pitch=["medium", "low"],
    contexts=["Audiobook", "Conversational"],
    type_=["prebuilt"],
    search="warm",
    page_size=50,
)

for voice in response.voices or []:
    print(
        f"{voice.id} | {voice.display_name} ({voice.language_code},"
        f" {voice.accent}, {voice.gender}, pitch={voice.pitch}):"
        f" {voice.description}"
    )

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI();

// Filter the Voice Library by language, gender, pitch, domain context, and keyword
const response = await ai.voices.list({
  language_code: ["en-US", "en-GB"],
  gender: ["female"],
  pitch: ["medium", "low"],
  contexts: ["Audiobook", "Conversational"],
  type: ["prebuilt"],
  search: "warm",
  page_size: 50,
});

for (const voice of response.voices ?? []) {
  console.log(
    `${voice.id} | ${voice.display_name} (${voice.language_code}, ${voice.accent}, ${voice.gender}, pitch=${voice.pitch}): ${voice.description}`
  );
}

curl -G "https://generativelanguage.googleapis.com/v1beta/voices" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  --data-urlencode "language_code=en-US" \
  --data-urlencode "language_code=en-GB" \
  --data-urlencode "gender=female" \
  --data-urlencode "pitch=medium" \
  --data-urlencode "context=Audiobook" \
  --data-urlencode "type=prebuilt" \
  --data-urlencode "search=warm" \
  --data-urlencode "page_size=50"

Lingue supportate

I modelli TTS rilevano automaticamente la lingua di inserimento. Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) supporta oltre 130 lingue e Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) supporta oltre 100 lingue:

Modelli supportati

Quando utilizzare un modello o l'altro

Entrambi i modelli Gemini 3.8 TTS condividono lo stesso schema dell'API e lo stesso formato di prompt, consentendoti di passare da uno all'altro con una singola modifica del parametro:

• Utilizza Gemini 3.8 Flash TTS (gemini-3.8-flash-tts) quando la massima fedeltà acustica, la recitazione sfumata e il controllo espressivo sono la priorità assoluta. È ideale per lavori creativi di qualità professionale, dialoghi complessi tra più persone, tag di burst vocali pesanti, pronunce difficili, dialetti regionali o di minoranze e narrazioni di lunga durata che richiedono una stabilità assoluta della voce e del tono della stanza.
• Utilizza Gemini 3.8 Flash-Lite TTS (gemini-3.8-flash-lite-tts) come sostituto rapido ed economico di gemini-3.1-flash-tts-preview. È ottimizzato per la produzione di massa di volumi elevati, le cascate di agenti vocali conversazionali, le funzionalità di lettura ad alta voce, la replica vocale affidabile e il parlato quotidiano di un singolo speaker nelle principali lingue.

Guida alla migrazione

Se esegui la migrazione da gemini-3.1-flash-tts-preview o da modelli Gemini TTS precedenti a Gemini 3.8 TTS:

1. Sposta le indicazioni stradali passo passo in speech_metadata: Gemini 3.8 TTS tratta il testo di input rigorosamente come una trascrizione letterale. Sposta le istruzioni di consegna sostenuta (style, ad esempio "whispering", "out of breath" o "speaking slowly") e le etichette di chi parla (speaker) in annotazioni speech_metadata strutturate anziché incorporare le indicazioni di scena nel testo della trascrizione.
2. Utilizza i tag in linea tra parentesi angolari solo per gli eventi vocali puntuali: mantieni le vocalizzazioni e le pause momentanee non vocali in linea nella trascrizione utilizzando le parentesi angolari (come <laugh>, <sigh>, <cough>, <breath> o <short pause>). Evita i tag degli effetti sonori (come applausi o rumori sordi) e inserisci gli stili di consegna in speech_metadata.style.
3. Specifica speaker in ogni turno nelle richieste con più interlocutori: ogni turno in una richiesta con più interlocutori deve includere esplicitamente speaker all'interno di speech_metadata corrispondente a uno degli interlocutori configurati.
4. Progetta in anticipo i personas con Voice Design: sostituisci i blocchi "Audio Profile" o "Director's Notes" di più paragrafi con una voce personalizzata creata in Voice Design, quindi trasferisci l'ID voice_... alle tue richieste TTS con stringhe style minime o vuote.
5. Tieni conto dell'output WAV (audio/wav) predefinito per le richieste unarie: a differenza di gemini-3.1-flash-tts-preview e dei modelli TTS precedenti (che restituivano PCM audio/l16 non elaborato senza intestazione per impostazione predefinita), Gemini 3.8 TTS restituisce audio WAV (audio/wav) con un'intestazione RIFF standard per impostazione predefinita per le richieste unarie.
   • Se in precedenza il tuo codice racchiudeva i byte PCM non elaborati in un'intestazione WAV (ad esempio, utilizzando il modulo wave di Python o ffmpeg), rimuovi il wrapper dell'intestazione manuale e scrivi i byte restituiti direttamente in un file .wav.
   • Se la pipeline richiede audio PCM non elaborato, mu-law o A-law senza intestazione, imposta esplicitamente response_format.mime_type su "audio/l16", "audio/mulaw" o "audio/alaw" (ad esempio, {"response_format": {"type": "audio", "mime_type": "audio/l16"}} nell'API Interactions o AUDIO_L16 in generateContent). Vedi Formati di output audio.

Guida ai prompt

I modelli Gemini 3.8 TTS trattano il testo di input rigorosamente come una trascrizione letterale. A differenza dei modelli di anteprima precedenti in cui le indicazioni sceniche erano incorporate nel testo normale, Gemini 3.8 TTS separa le indicazioni a livello di turno sostenute (speech_metadata) dai tag vocali incorporati in un determinato momento.

Campo Stile e tag in linea

Suddividi le istruzioni per le prestazioni in base all'ambito:

• Espressione a livello di turno (speech_metadata.style): inserisci gli attributi di espressione sostenuta, come emozione, prosodia, ritmo generale o stile di espressione (come "whispering", "out of breath", "muttering" o "sarcastic"), nel campo style di speech_metadata. Per creare un personaggio e una performance stabili nel tempo, progetta la persona in anticipo in Voice design e utilizza style solo per modifiche facoltative a livello di turno.
• Eventi puntuali (tag incorporati): inserisci brevi suoni vocali non parlati, respiri o pause all'interno della trascrizione utilizzando le parentesi angolari (<cough>, <breath>, <sigh>, <short pause>). Utilizza le parentesi angolari (<...>) per ottenere la massima qualità audio e limitati alle vocalizzazioni umane anziché agli effetti sonori non vocali.

Pacing e pause

Puoi controllare il ritmo e il silenzio a tre livelli di granularità:

• Punteggiatura e puntini di sospensione:utilizza virgole, trattini (--) e puntini di sospensione (...) per creare esitazioni naturali nella conversazione.
• Tag di pausa in linea:inserisci <short pause> o <long pause> nei punti esatti dello script in cui un oratore deve fare una pausa: text Hold on, let me think... <short pause> Alright, I've got it.
• Velocità a livello di turno:imposta "style": "speaking rapidly" o "style": "speaking slowly" in speech_metadata per controllare la velocità di pronuncia durante l'intero turno.

Prosodia e tono

Utilizza speech_metadata.style per controllare la prosodia, il tono e l'inflessione in un turno (ad esempio, "style": "high pitch, cheerful and excited inflection" o "style": "monotone and flat"). Se l'emozione o la prosodia cambia a metà del dialogo, dividi il copione in turni separati con valori style distinti per ogni turno.

Enfasi

Scrivi in maiuscolo parole specifiche nella trascrizione, insieme alla punteggiatura e ai tag vocali incorporati, per porre un'enfasi vocale naturale sulle parole chiave:

This is a VERY important point!
It was a VERY long day <sigh> ... nobody listens anymore.

Espressioni vocali e suoni non vocali

Inserisci le vocalizzazioni umane non vocali in linea utilizzando le parentesi angolari (<...>) nel punto esatto in cui deve essere riprodotto il suono. I tag vocali consigliati includono:

Interiezioni e voci sovrapposte

Nei dialoghi con più interlocutori, racchiudi le reazioni dell'ascoltatore tra caratteri pipe (|reaction|) all'interno del turno di un interlocutore per creare canali di ritorno naturali o sovrapposizioni di parlato senza dover creare un turno separato per ogni reazione.

• Scambi brevi di backchannel:inserisci brevi reazioni degli ascoltatori (|oh hmm|, |oh really?|, |absolutely|) all'interno del turno dell'oratore attivo:
  • Turno 1 (Persona A): "So the launch is Thursday |oh hmm| Are we actually ready?"
  • Turno 2 (Speaker B): "Ready enough |oh really?| The last blocker cleared this morning."
  • Turno 3 (Speaker A): "Then let's ship it |absolutely| and watch the dashboards."
• Discorso sovrapposto e alternato: utilizza più segmenti di pipe per simulare un discorso simultaneo o alternato tra due oratori (funziona meglio con gemini-3.8-flash-tts):
  • Countdown/coro simultaneo: "Let's surprise him on three |ok| ready?" seguito da "one. two. three. |happy| happy |birthday| birthday!"
  • Sovrapposizione completa degli speaker: "Hello |oh| there |my| it |goodness| must |gracious| be |would| almost |you| time |look| for |at that| dinner"

Coerenza tra le generazioni e cosa evitare

Segui queste linee guida per mantenere stabile l'identità vocale nei vari turni:

• Progetta le persona in anticipo nella progettazione vocale anziché utilizzare blocchi di stile lunghi: i paragrafi "Audio Profile" in formato lungo e gli elenchi puntati multipli "Director's Notes" riportati dai modelli precedenti sono la causa più comune di deriva della voce. Utilizza la stessa intuizione creativa in anticipo in Voice Design per generare un personaggio voice_... personalizzato persistente, quindi utilizza l'ID voce nelle chiamate TTS.
• Affidati al riferimento vocale per la stabilità (ometti le meta-istruzioni): i modelli Gemini 3.8 TTS sono addestrati per ancorarsi prima al riferimento audio. Non includere istruzioni che dicono al modello di mantenere la voce stabile (come "do not switch speaker identity" o "maintain identical timbre"): il testo aggiuntivo del prompt aumenta la deviazione. Elimina le istruzioni di stile non necessarie e lascia che il modello vari naturalmente intorno al punto stabile fornito dal riferimento vocale.
• Non provare a modificare i tratti immutabili di chi parla in style: evita di inserire età, genere, nomi o modifiche permanenti dell'accento in speech_metadata.style. Scegli invece una voce regionale dalla raccolta di voci estesa o creane una con Progettazione vocale.

Workflow consigliato

1. Crea il personaggio una sola volta: crea il tuo personaggio in Progettazione della voce o seleziona una voce regionale dalla raccolta di voci estesa che corrisponda alla lingua di destinazione e alla personalità.
2. Scrivi trascrizioni naturali con disfluenze:per ottenere la massima naturalezza, scrivi il text come una vera trascrizione del parlato, includendo disfluenze e esitazioni naturali (ad esempio, "Oh uh yeah I think... hm, so that's interesting").
3. Testa prima il TTS semplice: sintetizza la trascrizione con un campo style vuoto, poiché la maggior parte delle richieste non richiede alcuna istruzione style.
4. Aggiungi prompt style brevi solo per le modifiche:aggiungi una stringa style concisa (ad esempio "casual, friendly" o "muttering, then reassuring") solo per i turni che richiedono una modifica specifica della consegna e riutilizza la stessa stringa breve nei turni quando vuoi una base di riferimento coerente.

Agenti vocali e di dialogo multi-turno

Quando crei agenti vocali conversazionali in tempo reale o applicazioni multi-turno:

• Effettua una chiamata TTS per turno all'arrivo dei blocchi di testo LLM.
• Lascia che l'voice configurato (predefinito, progettato voice_... o replicato voice_... / voicekey_...) porti l'identità di chi parla attraverso i turni, non inviare mai un personaggio con un nome lungo a ogni turno.
• Lascia vuoto il campo style per turno o invia una breve stringa costante (ad esempio "casual, friendly") per l'intera conversazione.
• Suddividi le risposte lunghe dell'agente in turni più brevi anziché utilizzare prompt di stile più forti.

Limitazioni

• I modelli TTS accettano input di solo testo e generano output di solo audio.
• La generazione di più speaker con una sola richiesta (speech_config.speakers) supporta fino a due speaker che utilizzano voci predefinite. Per combinare voci personalizzate (voice_...) o replicate (voice_... / voicekey_...) in un dialogo con più personaggi, sintetizza singolarmente il turno di ogni interlocutore. Poiché le richieste unarie restituiscono audio/wav con un'intestazione RIFF di 44 byte per impostazione predefinita, richiedi PCM non elaborato ({"type": "audio", "mime_type": "audio/l16"}) o rimuovi l'intestazione WAV da ogni turno prima di concatenare i frame audio PCM a 24 kHz.
• Limiti di archiviazione e TTL della voce personalizzata:
  • Voci con stato (store=True, richieste o replicate): massimo 200 voci per progetto con un TTL di 1 anno (durata).
  • Chiavi vocali stateless (store=False, voicekey_...): TTL (durata) di 7 giorni.
• Consulta la sezione Lingue supportate per informazioni sulla copertura linguistica.

Passaggi successivi

• Crea personaggi vocali personalizzati dal linguaggio naturale con Voice design.
• Replica la voce di un oratore esistente in Replica vocale.
• Confronta le specifiche dei modelli nelle pagine dei modelli Gemini 3.8 Flash TTS e Gemini 3.8 Flash-Lite TTS.
• Esplora l'audio bidirezionale interattivo con l'API Live.