Gemini TTS 系列

Google 的 Gemini 語音合成模型，透過 OpenAI 相容的 POST /v1/audio/speech 呼叫，可用自然語言描述語氣與風格。

常用模型 ID（呼叫時原樣複製）

Gemini 3.8 Flash TTSgoogle/gemini-3.8-flash-tts

Gemini 3.8 Flash-Lite TTSgoogle/gemini-3.8-flash-lite-tts單價更低

全部 TTS 模型見模型頁。介面的通用參數見 Audio Speech API。

呼叫範例

Python

gemini_tts.py


import os
from openai import OpenAI
 
client = OpenAI(base_url="https://api.ofox.io/v1", api_key=os.environ["OFOX_API_KEY"])
 
with client.audio.speech.with_streaming_response.create(
    model="google/gemini-3.8-flash-tts",
    voice="Kore",
    input="今天的會議改到下午三點，請大家準時參加。",
    instructions="用沉穩、清晰的語氣朗讀，像新聞播報。",
    response_format="wav",
) as resp:
    resp.stream_to_file("speech.wav")

參數取值

重點voice 必填，取值為 Google 的音色名稱；輸出格式僅支援 wav 與 pcm。

參數	說明
`voice`	必填，Google 的音色名稱，如 `Kore`、`Puck`、`Zephyr`。完整清單見 Gemini 官方文件 · 音色。OpenAI 的音色名稱（如 `alloy`）無法使用
`response_format`	`wav`（預設）或 `pcm`，皆為 24 kHz、16 位元、單聲道。不支援 `mp3`、`opus`、`aac`、`flac`
`instructions`	用自然語言描述語氣、語速與風格，如「用歡快的語氣」「放慢語速」
`language_code`	語言代碼，如 `cmn-CN`、`en-US`，不傳時根據文字自動判斷
`stream_format`	傳入 `sse` 時以串流方式返回音訊片段，適合邊生成邊播放

需要 mp3 時，可先取得 wav，再用 ffmpeg 等工具轉換：ffmpeg -i speech.wav speech.mp3。

耗時與長文本

實測一句約 20 字的中文約 3 秒返回。約 6000 個字元的英文生成了約 9 分鐘的音訊，耗時約 105 秒，wav 檔案約 26 MB；長文本請將用戶端逾時設為 300 秒以上，或使用 stream_format: "sse" 串流取得。

常見錯誤

HTTP	錯誤原文	原因	處理方法
400	`voice is required for speech completion`	未傳 `voice`	傳入音色名稱，如 `Kore`
400	`Request contains an invalid argument.`	音色名稱不存在，例如傳入了 `alloy`	改用 Google 的音色名稱
400	`unsupported Gemini response_format: mp3`	格式不受支援	改用 `wav` 或 `pcm`

更多錯誤見 Audio Speech API。

官方文件

Gemini API · 語音生成

常見問題

Gemini TTS 的 voice 要填什麼？

填 Google 的音色名稱，如 Kore、Puck、Zephyr，完整清單見 Gemini 官方文件。voice 為必填，OpenAI 的 alloy 等音色無法使用。

Gemini TTS 能輸出 mp3 嗎？

不能，僅支援 wav 與 pcm（24 kHz、16 位元、單聲道）。需要 mp3 時請自行轉換，如 ffmpeg -i speech.wav speech.mp3。

Gemini TTS 怎麼控制語氣？

透過 instructions 參數用自然語言描述，例如「用歡快的語氣朗讀」「像新聞播報一樣沉穩」。

Gemini TTS 報錯 voice is required？

Gemini TTS 必須傳入 voice，例如 "voice": "Kore"。