使用 Gemini API 生成文字轉語音 (TTS)


您可以使用 Gemini TTS 模型 (gemini-3.8-flash-tts 或 gemini-3.8-flash-lite-tts),將文字合成為自然、生動的語音 (音訊)。使用 Firebase AI Logic 時,您可以直接從行動或網頁應用程式 (例如 Apple (Swift)、Android (Kotlin/Java)、網頁 (JavaScript)、Flutter (Dart) 或 Unity 應用程式) 提出這項要求。

文字轉語音 (TTS) 生成功能可控,也就是說,您提供要合成語音的確切文字,同時使用結構化中繼資料和內嵌語音標記,引導語音的傳達方式,例如情緒、語速、說話者聲音,以及笑聲或嘆氣等非語音聲音。您可以將 TTS 視為語音轉文字的反向操作。

這項功能可讓您建構以下功能:

  • 互動式故事和有聲書:朗讀長篇故事或角色扮演遊戲,角色會切換聲音、以重疊的附和聲互相回應,並調整情緒表達方式 (例如在懸疑情節中低語,或在笑話中大笑)。
  • 低延遲語音代理和助理:LLM 生成文字後,立即串流合成語音,在對話過程中保持一致的語音角色。
  • 多語言內容朗讀和語言家教:以超過 130 種語言和地區口音朗讀文章、食譜或學習教材,或在單一對話中流暢切換語言。

本指南說明如何生成單人或多人語音、串流音訊回覆、使用 SpeechMetadata 和內嵌標記控制語音呈現方式,以及從預先建構、資料庫或自訂語音中選擇。

跳轉至單一說話者程式碼 跳轉至多位說話者程式碼 跳轉至串流程式碼

TTS 與Live API的比較

文字轉語音 (TTS) 模型和 Live API 模型都是低延遲的語音生成模型,可設定不同的回覆語音和語言。不過,兩者的用途截然不同。

  • 文字轉語音 (TTS) 生成是單向要求/回應互動 (輸入文字,輸出音訊)。這項功能適用於需要精確朗讀所提供文字,並精細控制風格和聲音的情境,例如 Podcast 旁白、有聲書或朗讀文章。

  • Live API 生成支援雙向串流,可進行即時語音對話 (語音輸入、語音輸出)。這項功能適合用於動態對話情境,由模型決定要傳回的語音。請注意,最新的 Live API 模型也支援影片和圖片輸入。

事前準備

按一下您的Gemini API供應商,即可在這個頁面查看供應商專屬內容和程式碼。

如果尚未完成入門指南,請先完成。指南說明如何設定 Firebase 專案、將應用程式連結至 Firebase、新增 SDK、為所選 Gemini API 供應商初始化後端服務,以及建立 GenerativeModel 執行個體。

如要測試及反覆調整提示,建議使用 Google AI Studio。

支援這項功能的模型

  • gemini-3.8-flash-tts
  • gemini-3.8-flash-lite-tts
TTS 模型比較

這兩個 Gemini 3.x TTS 模型的要求結構定義和提示格式都相同。不過,以下列出各模型的適用情況。

功能或工作負載 gemini-3.8-flash-tts gemini-3.8-flash-lite-tts
主要優點 錄音室等級的高保真音質、細膩的語音表現,以及廣泛的方言支援 高處理量、低延遲和成本效益
最佳用途 有聲書、錄音室旁白、複雜的多人對話、頻繁出現的語音爆發標記、難以發音的字詞、地區方言 大量生成、即時語音代理串接、朗讀 UI 功能、日常單一說話者語音
支援的語言 132 種語言 103 種語言

根據文字生成語音

您可以根據文字輸入內容生成語音,包括單一說話者語音或雙人對話,並以完整 WAV 檔案 (generateContent) 或低延遲原始 PCM 音訊串流 (generateContentStream) 的形式輸出。

生成單一說話者的語音

試用這個範例前,請先完成本指南的「事前準備」一節,設定專案和應用程式。
在該節中,您也需要點選所選Gemini API供應商的按鈕,這樣這個頁面才會顯示供應商專屬內容。

生成單一說話者音訊的方法如下:

  1. 在 GenerationConfig 中,將 responseModalities 設為 AUDIO,並使用下列項目設定 SpeechConfig:

  2. 使用下列項目建立 TextPart:

    • (必要) 要朗讀的逐字稿。

    • (選用) 包含 style 說明的 SpeechMetadata (例如 "cheerful and friendly")。

  3. 呼叫 generateContent。根據預設,一元要求會在回應的內嵌資料部分,傳回完整的 WAV (audio/wav) 音訊檔案 (16 位元線性 PCM、24 kHz、單聲道,並包含標準 44 位元組 RIFF 標頭)。

Swift


import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Set `responseModalities` to include `.audio`.
// Configure a `SpeechConfig` with your chosen voice name (and optionally a language code).
let config = GenerationConfig(
  responseModalities: [.audio],
  speechConfig: SpeechConfig(voiceName: "Kore", languageCode: "en-US")
)

// Create a `GenerativeModel` instance with a model that supports speech generation.
let model = ai.generativeModel(
  modelName: "gemini-3.8-flash-tts",
  generationConfig: config
)

// Provide the verbatim text to synthesize as speech.
// Optionally provide turn-level style metadata.
let prompt = TextPart(
  "Have a wonderful day!",
  speechMetadata: SpeechMetadata(style: "cheerful and friendly")
)

// Call `generateContent` to generate the speech output.
let response = try await model.generateContent(prompt)

// Extract the WAV audio data and handle it for downstream use. For example:
for part in response.inlineDataParts {
  let wavData = part.data       // WAV audio bytes (24kHz, 1 channel, 16-bit PCM)
  let mimeType = part.mimeType  // for example: "audio/wav"
  print("Received audio data with MIME type: \(mimeType)")

  // Play the WAV audio data using your own playback helper (for example, with `AVAudioPlayer(data: wavData)`).
  playAudio(data: wavData)
}

Kotlin

如果是 Kotlin,這個 SDK 中的方法是暫停函式,需要從協同程式範圍呼叫。

// Set `responseModalities` to include `AUDIO`.
// Configure a `SpeechConfig` with your chosen voice name (and optionally a language code).
val config = generationConfig {
    responseModalities = listOf(ResponseModality.AUDIO)
    speechConfig = SpeechConfig(
        voice = Voice("Kore"),
        languageCode = "en-US"
    )
}

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports speech generation.
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "gemini-3.8-flash-tts",
        generationConfig = config
    )

// Provide the verbatim text to synthesize as speech.
// Optionally provide turn-level style metadata.
val prompt = content {
    text(
        text = "Have a wonderful day!",
        speechMetadata = SpeechMetadata(style = "cheerful and friendly")
    )
}

// Call `generateContent` to generate the speech output.
val response = model.generateContent(prompt)

// Extract the WAV audio data and handle it for downstream use. For example:
val part = response.candidates.firstOrNull()?.content?.parts?.firstOrNull()
if (part is InlineDataPart) {
    val wavData = part.inlineData  // WAV audio bytes (24kHz, 1 channel, 16-bit PCM)

    // Pass the audio data to your audio player or playback helper (which you'll need to implement).
    playAudio(wavData)
}

Java

如果是 Java,這個 SDK 中的串流方法會從 Reactive Streams 程式庫傳回 Publisher 類型。

// Set `responseModalities` to include `AUDIO`.
// Configure a `SpeechConfig` with your chosen voice name (and optionally a language code).
GenerationConfig config = new GenerationConfig.Builder()
    .setResponseModalities(Collections.singletonList(ResponseModality.AUDIO))
    .setSpeechConfig(new SpeechConfig(new Voice("Kore"), "en-US"))
    .build();

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports speech generation.
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
        .generativeModel("gemini-3.8-flash-tts", config);

// Use the GenerativeModelFutures Java compatibility layer.
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

// Provide the verbatim text to synthesize as speech.
// Optionally provide turn-level style metadata.
Content content = new Content.Builder()
    .addText("Have a wonderful day!", new SpeechMetadata(null, "cheerful and friendly"))
    .build();
Executor executor = Executors.newSingleThreadExecutor();

// Call `generateContent` to generate the speech output.
// Extract the WAV audio data and handle it for downstream use.
ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        Part part = result.getCandidates().get(0).getContent().getParts().get(0);
        if (part instanceof InlineDataPart) {
            byte[] wavData = ((InlineDataPart) part).getInlineData();  // WAV audio bytes (24kHz, 1 channel, 16-bit PCM)

            // Pass the audio data to your audio player or playback helper (which you'll need to implement).
            playAudio(wavData);
        }
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

Web


import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, ResponseModality } from "firebase/ai";

// TODO(developer): Replace with your app's Firebase configuration
const firebaseConfig = { /* ... */ };
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service.
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Set `responseModalities` to include `AUDIO`.
// Configure a `SpeechConfig` with your chosen voice name (and optionally a language code).
const generationConfig = {
  responseModalities: [ResponseModality.AUDIO],
  speechConfig: {
    voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } },
    languageCode: "en-US"
  }
};

// Create a `GenerativeModel` instance with a model that supports speech generation.
const model = getGenerativeModel(ai, {
  model: "gemini-3.8-flash-tts",
  generationConfig
});

// Provide the verbatim text to synthesize as speech.
// Optionally provide turn-level style metadata.
const prompt = [
  {
    type: "text",
    text: "Have a wonderful day!",
    speechMetadata: { style: "cheerful and friendly" }
  }
];

// Call `generateContent` to generate the speech output.
const result = await model.generateContent(prompt);
const inlineDataParts = result.response.inlineDataParts();

// Extract the WAV audio data and handle it for downstream use. For example:
if (inlineDataParts?.[0]) {
  const wavBase64 = inlineDataParts[0].inlineData.data;  // WAV audio bytes (24kHz, 1 channel, 16-bit PCM)
  // Decode base64 to ArrayBuffer
  const wavBuffer = Uint8Array.from(atob(wavBase64), c => c.charCodeAt(0)).buffer;

  // The response is a complete WAV file, so the Web Audio API can decode and play it directly.
  const audioCtx = new AudioContext();
  const audioBuffer = await audioCtx.decodeAudioData(wavBuffer);
  const source = audioCtx.createBufferSource();
  source.buffer = audioBuffer;
  source.connect(audioCtx.destination);
  source.start();
}

Dart


import 'package:firebase_ai/firebase_ai.dart';

// Set `responseModalities` to include `audio`.
// Configure a `SpeechConfig` with your chosen voice name (and optionally a language code).
final config = GenerationConfig(
  responseModalities: [ResponseModalities.audio],
  speechConfig: SpeechConfig(voiceName: 'Kore', languageCode: 'en-US'),
);

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports speech generation.
final model = FirebaseAI.googleAI().generativeModel(
  model: 'gemini-3.8-flash-tts',
  generationConfig: config,
);

// Provide the verbatim text to synthesize as speech.
// Optionally provide turn-level style metadata.
final prompt = Content.multi([
  TextPart(
    'Have a wonderful day!',
    speechMetadata: SpeechMetadata(style: 'cheerful and friendly'),
  ),
]);

// Call `generateContent` to generate the speech output.
final response = await model.generateContent([prompt]);

// Extract the WAV audio data and handle it for downstream use. For example:
final part = response.candidates.first.content.parts.first;
if (part is InlineDataPart && part.mimeType.startsWith('audio/')) {
  final Uint8List wavData = part.bytes;  // WAV audio bytes (24kHz, 1 channel, 16-bit PCM)

  // Play the WAV audio data using your preferred audio player or helper (which you'll need to implement).
  await playAudio(wavData);
}

Unity


using Firebase.AI;

// Initialize the Gemini Developer API backend service.
var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Set `responseModalities` to include `Audio`.
// Configure a `SpeechConfig` with your chosen voice name and language code.
var config = new GenerationConfig(
  responseModalities: new System.Collections.Generic.List<ResponseModality> { ResponseModality.Audio },
  speechConfig: SpeechConfig.UsePrebuiltVoice("Kore", "en-US")
);

// Create a `GenerativeModel` instance with a model that supports speech generation.
var model = ai.GetGenerativeModel(
  modelName: "gemini-3.8-flash-tts",
  generationConfig: config
);

// Provide the verbatim text to synthesize as speech.
// Optionally provide turn-level style metadata.
var prompt = new ModelContent(
  new ModelContent.TextPart(
    "Have a wonderful day!",
    new SpeechMetadata(speaker: null, style: "cheerful and friendly")
  )
);

// Call `GenerateContentAsync` to generate the speech output.
var response = await model.GenerateContentAsync(prompt);

// Extract the WAV audio data and handle it for downstream use. For example:
if (response.Candidates.Count > 0) {
  foreach (var part in response.Candidates[0].Content.Parts) {
    if (part is ModelContent.InlineDataPart inlineData) {
      byte[] wavData = inlineData.Data;  // WAV audio bytes (24kHz, 1 channel, 16-bit PCM)

      // Pass the audio data to your audio player or playback helper (which you'll need to implement).
      PlayAudio(wavData);
    }
  }
}

生成多人語音

試用這個範例前,請先完成本指南的「事前準備」一節,設定專案和應用程式。
在該節中,您也需要點選所選Gemini API供應商的按鈕,這樣這個頁面才會顯示供應商專屬內容。

您可以為每位講者指派不同的語音,並將每行對話做為獨立的 TextPart 傳遞,在單一要求中生成自然的雙人對話:

  1. 建立 MultiSpeakerVoiceConfig,將兩個說話者名稱 (例如 "Joe" 和 "Jane") 對應至其 SpeakerVoiceConfig 聲音。

  2. 在 GenerationConfig 中,將 responseModalities 設為 AUDIO,並將 MultiSpeakerVoiceConfig (和選用的 languageCode) 傳遞至 SpeechConfig。

  3. 提供 TextPart 物件的陣列或清單,具體來說,每個對話輪次一個 TextPart。在每個 TextPart 上,使用下列指令設定 SpeechMetadata:

    • (必要) speaker,與 MultiSpeakerVoiceConfig 中定義的其中一個說話者名稱相符。
    • (選用) style 說明 (例如 "cheerful and friendly")。
  4. 呼叫 generateContent。模型會合成完整對話,並傳回完整的 WAV (audio/wav) 音訊檔案。

Swift


import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Configure a `SpeechConfig` for multiple speakers, assigning a voice to each speaker.
let multiSpeechConfig = SpeechConfig(
  multiSpeakerVoiceConfig: MultiSpeakerVoiceConfig(
    speakerVoiceConfigs: [
      SpeakerVoiceConfig(speaker: "Joe", voiceName: "Puck"),
      SpeakerVoiceConfig(speaker: "Jane", voiceName: "Kore")
    ]
  ),
  languageCode: "en-US"
)

// Set `responseModalities` to include `.audio`.
let config = GenerationConfig(
  responseModalities: [.audio],
  speechConfig: multiSpeechConfig
)

// Create a `GenerativeModel` instance with a model that supports speech generation.
let model = ai.generativeModel(
  modelName: "gemini-3.8-flash-tts",
  generationConfig: config
)

// Provide one `TextPart` per dialogue turn, specifying the speaker and optional style in `SpeechMetadata`.
let prompt: [any PartsRepresentable] = [
  TextPart(
    "How's it going today, Jane?",
    speechMetadata: SpeechMetadata(speaker: "Joe", style: "cheerful and friendly")
  ),
  TextPart(
    "Not too bad, how about you?",
    speechMetadata: SpeechMetadata(speaker: "Jane", style: "calm and relaxed")
  )
]

// Call `generateContent` to generate the multi-speaker speech output.
let response = try await model.generateContent(prompt)

// Extract the WAV audio data and handle it for downstream use. For example:
for part in response.inlineDataParts {
  let wavData = part.data       // WAV audio bytes (24kHz, 1 channel, 16-bit PCM)
  let mimeType = part.mimeType  // for example: "audio/wav"
  print("Received audio data with MIME type: \(mimeType)")

  // Play the WAV audio data using your own playback helper (for example, with `AVAudioPlayer(data: wavData)`).
  playAudio(data: wavData)
}

Kotlin

如果是 Kotlin,這個 SDK 中的方法是暫停函式,需要從協同程式範圍呼叫。

// Configure a `SpeechConfig` for multiple speakers, assigning a voice to each speaker.
val multiSpeechConfig = SpeechConfig(
    multiSpeakerVoiceConfig = MultiSpeakerVoiceConfig(
        speakerVoiceConfigs = listOf(
            SpeakerVoiceConfig(speaker = "Joe", voice = Voice("Puck")),
            SpeakerVoiceConfig(speaker = "Jane", voice = Voice("Kore"))
        )
    ),
    languageCode = "en-US"
)

// Set `responseModalities` to include `AUDIO`.
val config = generationConfig {
    responseModalities = listOf(ResponseModality.AUDIO)
    speechConfig = multiSpeechConfig
}

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports speech generation.
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "gemini-3.8-flash-tts",
        generationConfig = config
    )

// Provide one text part per dialogue turn, specifying the speaker and optional style in `SpeechMetadata`.
val prompt = content {
    text(
        text = "How's it going today, Jane?",
        speechMetadata = SpeechMetadata(speaker = "Joe", style = "cheerful and friendly")
    )
    text(
        text = "Not too bad, how about you?",
        speechMetadata = SpeechMetadata(speaker = "Jane", style = "calm and relaxed")
    )
}

// Call `generateContent` to generate the multi-speaker speech output.
val response = model.generateContent(prompt)

// Extract the WAV audio data and handle it for downstream use. For example:
val part = response.candidates.firstOrNull()?.content?.parts?.firstOrNull()
if (part is InlineDataPart) {
    val wavData = part.inlineData  // WAV audio bytes (24kHz, 1 channel, 16-bit PCM)

    // Pass the audio data to your audio player or playback helper (which you'll need to implement).
    playAudio(wavData)
}

Java

如果是 Java,這個 SDK 中的串流方法會從 Reactive Streams 程式庫傳回 Publisher 類型。

// Configure a `SpeechConfig` for multiple speakers, assigning a voice to each speaker.
MultiSpeakerVoiceConfig multiSpeakerVoiceConfig = new MultiSpeakerVoiceConfig(
    Arrays.asList(
        new SpeakerVoiceConfig("Joe", new Voice("Puck")),
        new SpeakerVoiceConfig("Jane", new Voice("Kore"))
    )
);

SpeechConfig multiSpeechConfig = new SpeechConfig(multiSpeakerVoiceConfig, "en-US");

// Set `responseModalities` to include `AUDIO`.
GenerationConfig config = new GenerationConfig.Builder()
    .setResponseModalities(Collections.singletonList(ResponseModality.AUDIO))
    .setSpeechConfig(multiSpeechConfig)
    .build();

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports speech generation.
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
        .generativeModel("gemini-3.8-flash-tts", config);

// Use the `GenerativeModelFutures` Java compatibility layer.
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

// Provide one text part per dialogue turn, specifying the speaker and optional style in `SpeechMetadata`.
Content content = new Content.Builder()
    .addText(
        "How's it going today, Jane?",
        new SpeechMetadata("Joe", "cheerful and friendly"))
    .addText(
        "Not too bad, how about you?",
        new SpeechMetadata("Jane", "calm and relaxed"))
    .build();
Executor executor = Executors.newSingleThreadExecutor();

// Call `generateContent` to generate the multi-speaker speech output.
// Extract the WAV audio data and handle it for downstream use.
ListenableFuture<GenerateContentResponse> response = model.generateContent(content);
Futures.addCallback(response, new FutureCallback<GenerateContentResponse>() {
    @Override
    public void onSuccess(GenerateContentResponse result) {
        Part part = result.getCandidates().get(0).getContent().getParts().get(0);
        if (part instanceof InlineDataPart) {
            byte[] wavData = ((InlineDataPart) part).getInlineData();  // WAV audio bytes (24kHz, 1 channel, 16-bit PCM)

            // Pass the audio data to your audio player or playback helper (which you'll need to implement).
            playAudio(wavData);
        }
    }

    @Override
    public void onFailure(Throwable t) {
        t.printStackTrace();
    }
}, executor);

Web


import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, ResponseModality } from "firebase/ai";

// TODO(developer): Replace with your app's Firebase configuration
const firebaseConfig = { /* ... */ };
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service.
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Set `responseModalities` to include `AUDIO`.
// Configure a `SpeechConfig` for multiple speakers, assigning a voice to each speaker.
const generationConfig = {
  responseModalities: [ResponseModality.AUDIO],
  speechConfig: {
    multiSpeakerVoiceConfig: {
      speakerVoiceConfigs: [
        { speaker: "Joe", voiceConfig: { prebuiltVoiceConfig: { voiceName: "Puck" } } },
        { speaker: "Jane", voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } } }
      ]
    },
    languageCode: "en-US"
  }
};

// Create a `GenerativeModel` instance with a model that supports speech generation.
const model = getGenerativeModel(ai, {
  model: "gemini-3.8-flash-tts",
  generationConfig
});

// Provide one `TextPart` per dialogue turn, specifying the speaker and optional style in `speechMetadata`.
const prompt = [
  {
    type: "text",
    text: "How's it going today, Jane?",
    speechMetadata: { speaker: "Joe", style: "cheerful and friendly" }
  },
  {
    type: "text",
    text: "Not too bad, how about you?",
    speechMetadata: { speaker: "Jane", style: "calm and relaxed" }
  }
];

// Call `generateContent` to generate the multi-speaker speech output.
const result = await model.generateContent(prompt);
const inlineDataParts = result.response.inlineDataParts();

// Extract the WAV audio data and handle it for downstream use. For example:
if (inlineDataParts?.[0]) {
  const wavBase64 = inlineDataParts[0].inlineData.data;  // WAV audio bytes (24kHz, 1 channel, 16-bit PCM)
  // Decode base64 to ArrayBuffer
  const wavBuffer = Uint8Array.from(atob(wavBase64), c => c.charCodeAt(0)).buffer;

  // The response is a complete WAV file, so the Web Audio API can decode and play it directly.
  const audioCtx = new AudioContext();
  const audioBuffer = await audioCtx.decodeAudioData(wavBuffer);
  const source = audioCtx.createBufferSource();
  source.buffer = audioBuffer;
  source.connect(audioCtx.destination);
  source.start();
}

Dart


import 'package:firebase_ai/firebase_ai.dart';

// Configure a `SpeechConfig` for multiple speakers, assigning a voice to each speaker.
final multiSpeechConfig = SpeechConfig.multiSpeaker(
  multiSpeakerVoiceConfig: MultiSpeakerVoiceConfig(
    speakerVoiceConfigs: [
      SpeakerVoiceConfig(speaker: 'Joe', voiceName: 'Puck'),
      SpeakerVoiceConfig(speaker: 'Jane', voiceName: 'Kore'),
    ],
  ),
  languageCode: 'en-US',
);

// Set `responseModalities` to include `audio`.
final config = GenerationConfig(
  responseModalities: [ResponseModalities.audio],
  speechConfig: multiSpeechConfig,
);

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports speech generation.
final model = FirebaseAI.googleAI().generativeModel(
  model: 'gemini-3.8-flash-tts',
  generationConfig: config,
);

// Provide one `TextPart` per dialogue turn, specifying the speaker and optional style in `SpeechMetadata`.
final prompt = Content.multi([
  TextPart(
    "How's it going today, Jane?",
    speechMetadata: SpeechMetadata(speaker: 'Joe', style: 'cheerful and friendly'),
  ),
  TextPart(
    'Not too bad, how about you?',
    speechMetadata: SpeechMetadata(speaker: 'Jane', style: 'calm and relaxed'),
  ),
]);

// Call `generateContent` to generate the multi-speaker speech output.
final response = await model.generateContent([prompt]);

// Extract the WAV audio data and handle it for downstream use. For example:
final part = response.candidates.first.content.parts.first;
if (part is InlineDataPart && part.mimeType.startsWith('audio/')) {
  final Uint8List wavData = part.bytes;  // WAV audio bytes (24kHz, 1 channel, 16-bit PCM)

  // Play the WAV audio data using your preferred audio player or helper (which you'll need to implement).
  await playAudio(wavData);
}

Unity


using Firebase.AI;

// Initialize the Gemini Developer API backend service.
var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Configure a `SpeechConfig` for multiple speakers, assigning a voice to each speaker.
var multiSpeakerVoiceConfig = new MultiSpeakerVoiceConfig(
  new System.Collections.Generic.List<SpeakerVoiceConfig> {
    SpeakerVoiceConfig.UsePrebuiltVoice("Joe", "Puck"),
    SpeakerVoiceConfig.UsePrebuiltVoice("Jane", "Kore")
  }
);

var multiSpeechConfig = SpeechConfig.UseMultiSpeakerVoice(multiSpeakerVoiceConfig, "en-US");

// Set `responseModalities` to include `Audio`.
var config = new GenerationConfig(
  responseModalities: new System.Collections.Generic.List<ResponseModality> { ResponseModality.Audio },
  speechConfig: multiSpeechConfig
);

// Create a `GenerativeModel` instance with a model that supports speech generation.
var model = ai.GetGenerativeModel(
  modelName: "gemini-3.8-flash-tts",
  generationConfig: config
);

// Provide one `TextPart` per dialogue turn, specifying the speaker and optional style in `SpeechMetadata`.
var prompt = new ModelContent(
  new ModelContent.TextPart(
    "How's it going today, Jane?",
    new SpeechMetadata(speaker: "Joe", style: "cheerful and friendly")
  ),
  new ModelContent.TextPart(
    "Not too bad, how about you?",
    new SpeechMetadata(speaker: "Jane", style: "calm and relaxed")
  )
);

// Call `GenerateContentAsync` to generate the multi-speaker speech output.
var response = await model.GenerateContentAsync(prompt);

// Extract the WAV audio data and handle it for downstream use. For example:
if (response.Candidates.Count > 0) {
  foreach (var part in response.Candidates[0].Content.Parts) {
    if (part is ModelContent.InlineDataPart inlineData) {
      byte[] wavData = inlineData.Data;  // WAV audio bytes (24kHz, 1 channel, 16-bit PCM)

      // Pass the audio data to your audio player or playback helper (which you'll need to implement).
      PlayAudio(wavData);
    }
  }
}

逐句回覆

試用這個範例前,請先完成本指南的「事前準備」一節,設定專案和應用程式。
在該節中,您也需要點選所選Gemini API供應商的按鈕,這樣這個頁面才會顯示供應商專屬內容。

如要縮短第一段音訊生成時間 (TTFA) 並即時播放,可以在生成音訊回覆時串流播放,不必等待整個片段生成完畢。串流功能適用於單一說話者和多位說話者設定。

如要串流語音,請呼叫 generateContentStream,而非 generateContent。與一元要求 (傳回 WAV 檔案) 不同,串流要求會傳回無標頭的原始 16 位元帶正負號小端序 PCM 區塊 (audio/l16、24 kHz、單聲道),因此您可以直接將每個區塊附加至音訊輸出緩衝區。

Swift


import FirebaseAILogic

// Initialize the Gemini Developer API backend service.
let ai = FirebaseAI.firebaseAI(backend: .googleAI())

// Set `responseModalities` to include `.audio`.
// Configure a `SpeechConfig` with your chosen voice name (and optionally a language code).
let config = GenerationConfig(
  responseModalities: [.audio],
  speechConfig: SpeechConfig(voiceName: "Kore")
)

// Create a `GenerativeModel` instance with a model that supports speech generation.
let model = ai.generativeModel(
  modelName: "gemini-3.8-flash-tts",
  generationConfig: config
)

// Provide the verbatim text to synthesize as speech.
// Optionally provide turn-level style metadata.
let prompt = TextPart(
  "Tell me a story about a brave knight.",
  speechMetadata: SpeechMetadata(style: "warm, engaging audiobook narrator")
)

// Call `generateContentStream` to stream the speech output as it is generated.
let responseStream = try model.generateContentStream(prompt)

// Extract the raw PCM audio chunks and queue them for playback:
for try await chunk in responseStream {
  for part in chunk.inlineDataParts {
    let pcmChunk = part.data  // Headerless raw PCM bytes (24kHz, 1 channel, 16-bit)

    // Append the audio chunk to your audio queue/buffer for playback (using a helper you implement).
    appendAudioChunk(pcmChunk)
  }
}

Kotlin

如果是 Kotlin,這個 SDK 中的方法是暫停函式,需要從協同程式範圍呼叫。

// Set `responseModalities` to include `AUDIO`.
// Configure a `SpeechConfig` with your chosen voice name (and optionally a language code).
val config = generationConfig {
    responseModalities = listOf(ResponseModality.AUDIO)
    speechConfig = SpeechConfig(voice = Voice("Kore"))
}

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports speech generation.
val model = Firebase.ai(backend = GenerativeBackend.googleAI())
    .generativeModel(
        modelName = "gemini-3.8-flash-tts",
        generationConfig = config
    )

// Provide the verbatim text to synthesize as speech.
// Optionally provide turn-level style metadata.
val prompt = content {
    text(
        text = "Tell me a story about a brave knight.",
        speechMetadata = SpeechMetadata(style = "warm, engaging audiobook narrator")
    )
}

// Call `generateContentStream` to stream the speech output as it is generated.
// Extract the raw PCM audio chunks and queue them for playback.
model.generateContentStream(prompt).collect { chunk ->
    val part = chunk.candidates.firstOrNull()?.content?.parts?.firstOrNull()
    if (part is InlineDataPart) {
        val pcmChunk = part.inlineData  // Headerless raw PCM bytes (24kHz, 1 channel, 16-bit)

        // Append the audio chunk to your audio queue/buffer for playback (using a helper you implement).
        appendAudioChunk(pcmChunk)
    }
}

Java

如果是 Java,這個 SDK 中的串流方法會從 Reactive Streams 程式庫傳回 Publisher 類型。

// Set `responseModalities` to include `AUDIO`.
// Configure a `SpeechConfig` with your chosen voice name (and optionally a language code).
GenerationConfig config = new GenerationConfig.Builder()
    .setResponseModalities(Collections.singletonList(ResponseModality.AUDIO))
    .setSpeechConfig(new SpeechConfig(new Voice("Kore")))
    .build();

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports speech generation.
GenerativeModel ai = FirebaseAI.getInstance(GenerativeBackend.googleAI())
        .generativeModel("gemini-3.8-flash-tts", config);

// Use the `GenerativeModelFutures` Java compatibility layer.
GenerativeModelFutures model = GenerativeModelFutures.from(ai);

// Provide the verbatim text to synthesize as speech.
// Optionally provide turn-level style metadata.
Content content = new Content.Builder()
    .addText(
        "Tell me a story about a brave knight.",
        new SpeechMetadata(null, "warm, engaging audiobook narrator"))
    .build();

// Call `generateContentStream` to stream the speech output as it is generated.
Publisher<GenerateContentResponse> streamingResponse =
    model.generateContentStream(content);

// Extract the raw PCM audio chunks and queue them for playback.
streamingResponse.subscribe(new Subscriber<GenerateContentResponse>() {
  @Override
  public void onSubscribe(Subscription s) {
      s.request(Long.MAX_VALUE);
  }

  @Override
  public void onNext(GenerateContentResponse chunk) {
      Part part = chunk.getCandidates().get(0).getContent().getParts().get(0);
      if (part instanceof InlineDataPart) {
          byte[] pcmChunk = ((InlineDataPart) part).getInlineData();  // Headerless raw PCM bytes (24kHz, 1 channel, 16-bit)

          // Append the audio chunk to your audio queue/buffer for playback (using a helper you implement).
          appendAudioChunk(pcmChunk);
      }
  }

  @Override
  public void onComplete() {
      // Audio stream complete.
  }

  @Override
  public void onError(Throwable t) {
      t.printStackTrace();
  }
});

Web


import { initializeApp } from "firebase/app";
import { getAI, getGenerativeModel, GoogleAIBackend, ResponseModality } from "firebase/ai";

// TODO(developer): Replace with your app's Firebase configuration
const firebaseConfig = { /* ... */ };
const firebaseApp = initializeApp(firebaseConfig);

// Initialize the Gemini Developer API backend service.
const ai = getAI(firebaseApp, { backend: new GoogleAIBackend() });

// Set `responseModalities` to include `AUDIO`.
// Configure a `SpeechConfig` with your chosen voice name (and optionally a language code).
const generationConfig = {
  responseModalities: [ResponseModality.AUDIO],
  speechConfig: {
    voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } }
  }
};

// Create a `GenerativeModel` instance with a model that supports speech generation.
const model = getGenerativeModel(ai, {
  model: "gemini-3.8-flash-tts",
  generationConfig
});

// Provide the verbatim text to synthesize as speech.
// Optionally provide turn-level style metadata.
const prompt = [
  {
    type: "text",
    text: "Tell me a story about a brave knight.",
    speechMetadata: { style: "warm, engaging audiobook narrator" }
  }
];

// Call `generateContentStream` to stream the speech output as it is generated.
const result = await model.generateContentStream(prompt);

// Extract the raw PCM audio chunks and queue them for playback:
const playbackQueue = [];
for await (const chunk of result.stream) {
  const inlineDataParts = chunk.inlineDataParts();
  if (inlineDataParts?.[0]) {
    const pcmBase64 = inlineDataParts[0].inlineData.data;  // Headerless raw PCM bytes (24kHz, 1 channel, 16-bit)
    const pcmBuffer = Uint8Array.from(atob(pcmBase64), c => c.charCodeAt(0)).buffer;

    // Append the audio chunk to your audio queue/buffer for playback.
    // In a real app, start playing chunks as they arrive (rather than waiting for
    // the whole stream to finish) to get the low-latency benefit of streaming.
    playbackQueue.push(pcmBuffer);
  }
}

// To play back an array of PCM buffers in sequence, pass them to your playback helper (which you'll need to write).
processPlaybackQueue(playbackQueue);

Dart


import 'package:firebase_ai/firebase_ai.dart';

// Set `responseModalities` to include `audio`.
// Configure a `SpeechConfig` with your chosen voice name (and optionally a language code).
final config = GenerationConfig(
  responseModalities: [ResponseModalities.audio],
  speechConfig: SpeechConfig(voiceName: 'Kore'),
);

// Initialize the Gemini Developer API backend service.
// Create a `GenerativeModel` instance with a model that supports speech generation.
final model = FirebaseAI.googleAI().generativeModel(
  model: 'gemini-3.8-flash-tts',
  generationConfig: config,
);

// Provide the verbatim text to synthesize as speech.
// Optionally provide turn-level style metadata.
final prompt = Content.multi([
  TextPart(
    'Tell me a story about a brave knight.',
    speechMetadata: SpeechMetadata(style: 'warm, engaging audiobook narrator'),
  ),
]);

// Call `generateContentStream` to stream the speech output as it is generated.
final responseStream = model.generateContentStream([prompt]);

// Extract the raw PCM audio chunks and queue them for playback:
await for (final chunk in responseStream) {
  final part = chunk.candidates.first.content.parts.first;
  if (part is InlineDataPart && part.mimeType.startsWith('audio/')) {
    final Uint8List pcmChunk = part.bytes;  // Headerless raw PCM bytes (24kHz, 1 channel, 16-bit)

    // Append the audio chunk to your audio queue/buffer for playback (using a helper you implement).
    appendAudioChunk(pcmChunk);
  }
}

Unity


using System.Collections.Generic;
using System.Linq;
using Firebase.AI;

// Initialize the Gemini Developer API backend service.
var ai = FirebaseAI.GetInstance(FirebaseAI.Backend.GoogleAI());

// Set `ResponseModalities` to include `Audio`.
// Configure a `SpeechConfig` with your chosen voice name (and optionally a language code).
var config = new GenerationConfig(
    responseModalities: new List<ResponseModality> { ResponseModality.Audio },
    speechConfig: SpeechConfig.UsePrebuiltVoice("Kore")
);

// Create a `GenerativeModel` instance with a model that supports speech generation.
var model = ai.GetGenerativeModel(
    modelName: "gemini-3.8-flash-tts",
    generationConfig: config
);

// Provide the verbatim text to synthesize as speech.
// Optionally provide turn-level style metadata.
var prompt = new ModelContent(
    new ModelContent.TextPart(
        "Tell me a story about a brave knight.",
        new SpeechMetadata(speaker: null, style: "warm, engaging audiobook narrator")
    )
);

// Call `GenerateContentStreamAsync` to stream the speech output as it is generated.
var responseStream = model.GenerateContentStreamAsync(prompt);

// Extract the raw PCM audio chunks and queue them for playback:
await foreach (var response in responseStream)
{
    var audioParts = response.Candidates.FirstOrDefault().Content.Parts
                            .OfType<ModelContent.InlineDataPart>();

    foreach (var part in audioParts)
    {
        byte[] pcmChunk = part.Data; // Headerless raw PCM bytes (24kHz, 1 channel, 16-bit)

        // Append the audio chunk to your audio queue/buffer for playback (using a helper you implement).
        AppendAudioChunk(pcmChunk);
    }
}



使用中繼資料和內嵌標記控制語音輸出

Gemini 3.x TTS 模型會將每個 TextPart 內的 text 視為要朗讀的逐字稿。請勿在文字字串中寫入敘述性指示 (例如 "Say cheerfully:"),否則模型可能會朗讀這些字詞。

你可以使用下列技巧,引導語音生成效果:

語音層級 style 和內嵌語音標記

請依範圍將效能指示拆分為 SpeechMetadata 和內嵌角括號標記 (<...>)。

範圍 放置位置 控制項目 範例
轉彎時
(在整個轉彎過程中持續作用)
SpeechMetadata.style 情緒、角色、語氣、語調、音高和整體語速 "cheerful and friendly"、
"whispered, nervous"、
"speaking rapidly"、
"out of breath"、
"sarcastic"
時間點
(本地化至句子中的特定時刻)
使用 <...> 內嵌在 TextPart 文字中 非語音的人聲爆發、呼吸、停頓或短暫的語氣轉變 "Wait... <short pause> did you hear that? <gasp> Someone's at the door."

語速、停頓、音高和強調

  • 標點符號和刪節號:在轉錄稿中使用逗號、破折號 (--) 和刪節號 (...),創造自然的措辭和猶豫感。

  • 明確的暫停標記:在說話者應暫停的確切位置,內嵌插入 <short pause> 或 <long pause>:

    Hold on, let me think... <short pause> Alright, I've got it.
    
  • 語速和音調:在 SpeechMetadata 中設定 style,控制該段落的整體語速、音調或語調變化 (例如 "speaking rapidly and excitedly"、"speaking slowly" 或 "monotone and flat")。如果情緒或語速在獨白中途發生變化,請將腳本拆分為不同的 TextPart 段落,每個段落都有各自的 style。

  • 強調字詞:將轉錄稿中的特定字詞大寫,以強調這些字詞:

    It was a VERY long day <sigh> ... nobody listens anymore.
    

人聲和非語音

使用角括號 (<...>),在聲音應出現的確切字詞邊界插入非語音人類發聲。請使用人類發聲,而非非人聲的音效。建議使用的標記如下:

<argh> <exhales> <heavy breath> <scream> <snort>
<breath> <gasp> <hiss> <short pause> <sob>
<cackle> <giggle> <laugh> /
<laughter>
<shout> <throat-clearing>
<cheer> <groan> <long pause> <shriek> <tsk>
<chuckle> /
<chuckles>
<growl> <moan> <sigh> /
<sighs>
<whimper>
<cough> <grr> <pant> <sneeze> <whispers> /
<whispering>
<cry> <grunt> <pff> /
<phew>
<snicker> <yawn>

附和語和語音重疊

在多人對話中,你可以在發言者的轉錄稿中,使用管道字元 (|reaction|) 包裹聽眾的簡短反應。非發言者自然地插話,不需要另外輪流:

  • 聽眾簡短回應:

    • Turn 1 (speaker: "Joe"): "So the launch is Thursday |oh hmm| Are we actually ready?"
    • Turn 2 (speaker: "Jane"): "Ready enough |oh really?| The last blocker cleared this morning."
  • 重疊語音:您可以使用多個管道區隔來模擬同時語音 (最適合搭配 gemini-3.8-flash-tts 使用),例如:

    • Turn 1 (speaker: "Joe"): "Let's surprise him on three |ok| ready?"
    • Turn 2 (speaker: "Jane"): "one. two. three. |happy| happy |birthday| birthday!"

一致性最佳做法

  • 先測試不含 style 的效果,再加入簡潔的 style 調整:大多數要求在 style 欄位留空時,聽起來都很自然。只有在需要對特定語音片段進行調整時,才加入簡短的 style 詞組 (例如 "casual, friendly" 或 "reflective and awe-inspired"),並在需要一致的基準時,在不同語音片段中重複使用相同的簡短字串。

  • 撰寫自然的口語轉錄稿:直接在轉錄稿文字中加入對話縮寫和自然的不流暢語句 (例如 "Oh, uh, yeah I think... hm, that's interesting")。

  • 避免使用舊版 [Audio Profile] 區塊和中繼指令:長篇角色設定段落、[Director's Notes] 區塊或 "maintain identical timbre" 等中繼指令,會增加語氣偏離的機率。請改從擴充語音庫選擇相符的語音,或使用語音設計功能建立固定的角色語音。

  • 請勿嘗試覆寫 style 中的不可變語音特徵:請避免使用 SpeechMetadata.style 變更語音的年齡、性別或永久口音。請改為選取或設計具有這些特徵的語音。



支援的語音

Gemini 3.x TTS 模型支援三種指定語音的方式:

所有語音都支援多種語言,也就是說,您可以使用同一種語音,以任何支援的語言生成語音,同時保持一致的說話者身分。舉例來說,如果將語音設為預先建構的 Kore 語音,並以西班牙文、北印度文和越南文傳送提示,則回覆都會使用各語言的 Kore 語音。30 種核心預建語音是一般用途多語言語音,而擴充語音庫語音和自訂語音則是以主要語言代碼或區域口音為基礎。這表示他們仍可說其他語言,但在主要語言地區聽起來最道地。

核心預建語音

Gemini 文字轉語音模型支援 30 種核心預建語音 (例如 Kore、Puck、Zephyr、Charon 和 Fenrir),每種語音都有獨特的人聲特徵。在 SpeechConfig 中傳遞語音名稱 (如本頁前面的單一說話者和多位說話者範例所示)。

擴充語音庫中的預設語音

除了 30 種預建語音外,擴充語音庫還提供超過 2,000 種精選預設語音,涵蓋多種語言、地區口音、年齡層、角色人物和用途 (例如有聲書、客服專員和新聞播報員)。

如要在應用程式中使用擴充語音庫的任何語音,請按照下列步驟操作:

  1. 使用下列其中一種方法瀏覽及預覽語音:

  2. 將程式庫語音的 id 字串做為語音名稱傳遞至 SpeechConfig (類似於本頁稍早的單一說話者範例)。

自訂語音:語音設計和語音複製

Gemini 3.x TTS 模型也支援使用下列任一選項的 Custom Voice:

  • 語音設計(預先發布版):使用自然語言描述說話者的年齡、音色、口音和角色,即可生成獨特的自訂語音,不需任何參考音訊。傳回儲存的 Voice ID (voice_...)。

  • 語音複製(預先發布版):根據參考錄音和口頭同意錄音,複製說話者的聲音、語調和語速。傳回專案儲存的語音 ID (voice_...),或無狀態、由應用程式管理的語音複製金鑰 (voicekey_...)。

在 Firebase AI Logic 應用程式中使用自訂語音

建立及管理自訂語音是管理或伺服器端作業,因此 Firebase AI Logic 用戶端 SDK 不會直接公開語音管理端點 (CreateVoice、ListVoices、DeleteVoice)。

如要使用自訂語音,請改為執行下列操作:

  1. 使用下列任一選項建立自訂語音:

    • 使用 Google AI Studio 或 Agent  Studio 取得 voice_<id> 或 voicekey_<id> ID。

    • 使用 Voices API 取得 voice_<id> 或 voicekey_<id> ID。如要瞭解詳情,請參閱所選 Gemini API 供應商的文件:

  2. 將 voice_<id> 或 voicekey_<id> 字串做為語音名稱傳遞至 SpeechConfig (類似於本頁稍早的單一說話者範例)。

使用自訂語音時,請注意下列規定:

  • 位置 (Agent Platform Gemini API (formerly Vertex AI)):自訂語音 (voice_... 和 voicekey_...) 僅支援 global 位置 (使用 Firebase AI Logic 時的預設位置)。

  • 單一說話者要求:MultiSpeakerVoiceConfig 僅支援核心預建語音。如要在多角色對話中使用自訂設計或複製的語音,請在個別的單一說話者要求中,合成每個角色的語音。

  • 保留和到期:儲存的自訂語音 (voice_...) 如果 1 年未使用,就會到期 (每次合成要求都會重設 1 年保留計時器);無狀態語音複製金鑰 (voicekey_...) 則會在建立 7 天後到期。

支援的語言

Gemini 3.x TTS 模型會自動偵測輸入文字的語言,包括提示在多位說話者對話中切換語言的情況。

  • Gemini 3.8 Flash TTS (gemini-3.8-flash-tts):支援 132 種語言。
  • Gemini 3.8 Flash‑Lite TTS (gemini-3.8-flash-lite-tts):支援 103 種語言。

(選用) 明確設定語言代碼

如要明確限制語音合成至特定語言代碼,可以在 SpeechConfig 中傳遞 BCP-47 languageCode:



音訊輸出格式

InlineDataPart 傳回的預設音訊格式取決於您提出的是一元要求或串流要求:

要求方法 預設傳回的 MIME 類型 音訊格式詳細資料
一元
(generateContent)
audio/wav 完整的 WAV 檔案 (16 位元線性 PCM、24 kHz、單聲道、小端序),包含標準 44 位元組 RIFF 標頭。

可直接透過標準平台音訊播放器播放 (例如 Apple 平台上的 AVAudioPlayer、Web Audio decodeAudioData 或檔案播放器)。

串流
(generateContentStream)
audio/l16 無標頭原始 16 位元帶正負號小端序 PCM 區塊,24 kHz,單聲道。

專為低延遲緩衝區佇列和串連而設計,不含個別區塊檔案標頭。



限制與需求

使用 Gemini 3.x TTS 模型時,請注意下列限制和規定:

  • 僅限文字輸入,僅限音訊輸出:TTS 模型僅接受文字輸入 (TextPart),且 responseModalities 必須設為 AUDIO。

  • 僅逐字合成:模型會逐字朗讀提供的轉錄稿,不會生成對話文字回覆。

  • 詞元限制:每項要求的輸入詞元上限為 8,192 個,輸出詞元上限為 16,384 個。

  • 多位說話者限制:MultiSpeakerVoiceConfig 必須有 2 位說話者,且僅支援核心預建語音。在多位說話者的要求中,每個 TextPart 都必須包含與其中一位設定說話者相符的 SpeechMetadata.speaker。

  • 不支援的參數和方法:

    • Firebase AI Logic SDK 尚未支援在 GenerationConfig 中設定 responseFormat,以覆寫預設音訊輸出格式。
    • 不支援設定 systemInstruction、temperature、topP、topK、candidateCount、presencePenalty 或 frequencyPenalty,否則要求會失敗並傳回 400 INVALID_ARGUMENT 錯誤。
    • TTS 模型不支援呼叫 countTokens (詞元計數會在回覆的 usageMetadata 中傳回)。
  • 位置 (Agent Platform Gemini API (formerly Vertex AI)):自訂語音 (voice_... 和 voicekey_...) 必須使用 global 位置 (使用 Firebase AI Logic 時的預設位置)。



從 gemini-3.1-flash-tts-preview 遷移

gemini-3.8-flash-tts 和 gemini-3.8-flash-lite-tts 都使用相同的要求結構。請參閱模式比較表,選擇最適合工作負載的替代模型,並按照下列方式更新程式碼:

Area gemini-3.1-flash-tts-preview (舊版) gemini-3.8-flash-tts和
gemini-3.8-flash-lite-tts
實踐方式和方向 嵌入提示文字。例如:
"Say cheerfully: ..."、
[Audio Profile]、
[Director's Notes]
在每個TextPart中傳入 SpeechMetadata(style: "...")

TextPart 文字必須與口述內容逐字稿完全一致。

多人對話 單一字串,內嵌 "Speaker: ..." 前置字元 每個對話輪次一個 TextPart,每個 TextPart 都有 SpeechMetadata(speaker: "...", style: "...")
內嵌語音標記 方括號。例如:
[sigh] 或 [laughs]
角括號。例如:
<sigh> 或 <laugh> 或 <short pause>

直接在文字中寫下口語不流暢的內容,例如 "uhm"。

預設一元音訊格式 (generateContent) 無標頭原始 16 位元 PCM (audio/pcm、24 kHz、單聲道) 完整 WAV 檔案 (audio/wav、16 位元 PCM、24 kHz、單聲道,含 44 位元組 RIFF 標頭)

串流 (generateContentStream) 仍是無標頭的原始 16 位元 PCM (audio/l16)。

系統指令、溫度、Top-P、Top-K 已忽略 因 400 INVALID_ARGUMENT 錯誤而遭拒。請從模型設定中移除這些參數。

遷移工作檢查清單

  • 升級至最新版本 Firebase AI Logic SDK,並將模型名稱更新為 gemini-3.8-flash-tts 或 gemini-3.8-flash-lite-tts。

  • 將樣式指令移至 SpeechMetadata.style:從提示字串中移除 "Say cheerfully:" 前置字元、[Audio Profile]、[Scene] 和 [Director's Notes] 區塊,以免模型朗讀這些內容。請改為在 SpeechMetadata.style 中傳遞簡潔的樣式說明。

  • 將多位說話者的腳本分割成不同的 TextPart 語音片段:將 "Joe: ... \n Jane: ..." 文字區塊替換為 TextPart 物件的陣列/清單,其中每個語音片段都會設定 SpeechMetadata.speaker。

  • 將 [...] 標記轉換為 <...> 標記:將方括號音訊標記 (例如 [whispers]、[sighs]、[laughs]) 替換為角括號人聲標記 (例如 <whispers>、<sigh>、<laugh>、<short pause>)。

  • 更新一元音訊播放:generateContent 現在會傳回完整的 WAV 檔案 (含 44 位元組 RIFF 標頭),而非無標頭的原始 PCM,因此請移除任何手動將 WAV 標頭附加至一元回應的程式碼 (如果將原始 PCM 樣本饋送至低階緩衝區 API,例如 Android 的 AudioTrack 或 Unity 的 AudioClip,則請略過 44 位元組標頭)。

  • 移除不支援的設定參數:從 TTS GenerativeModel 設定中移除 temperature、topP、topK、candidateCount、presencePenalty、frequencyPenalty 和 systemInstruction。



你還可以做些什麼?

試用其他功能

瞭解如何控管內容生成

您也可以使用 Google AI Studio 測試提示和模型設定,甚至取得生成的程式碼片段。

進一步瞭解支援的模型

瞭解適用於各種用途的模型,以及配額和定價。


提供 Firebase AI Logic 使用體驗的意見回饋