88API 語音介面:TTS 與 STT
Grok 與 Gemini 語音模型接入文件:/v1/audio/speech 語音合成、WebSocket 串流語音合成、Grok 即時語音對話、/v1/audio/transcriptions 與音訊對話轉寫,包含全部音色、輸出格式、請求欄位、cURL、OpenAI SDK、Python 和 Node.js 範例。
88API 提供 Grok 和 Gemini 兩組語音模型。語音合成(TTS)和語音轉文字(STT)的模型、介面和欄位各不相同,請依下表選擇。
模型與介面
| 能力 | 模型 | 介面 | 計費依據 |
|---|---|---|---|
| 語音合成 | grok-tts | POST /v1/audio/speech | 輸入字元數 |
| 串流語音合成 | grok-tts | WebSocket /v1/tts | 輸入字元數 |
| 即時語音對話 | grok-voice-latest、grok-voice-3.0 | WebSocket /v1/realtime | 通話時長 |
| 語音合成 | gemini-3.8-flash-tts | Gemini 原生 generateContent(回傳音訊下載連結) | Token |
| 語音轉文字 | grok-stt | POST /v1/audio/transcriptions | 音訊時長 |
| 語音轉文字 | gemini-3-stt、gemini-3.5-stt、gemini-3.5-transcribe | POST /v1/audio/transcriptions、POST /v1/chat/completions(音訊輸入),或 Gemini 原生 generateContent | Token |
- 價格以控制台模型廣場顯示為準。令牌分組選擇「语音模型」(控制台顯示的分組名稱)或自動分組。
- 語音模型只能使用上表中的介面。用對話、Responses 或 Messages 介面呼叫 TTS 模型或
grok-stt會回傳400,提示改用正確的介面。 - 不提供
/v1/audio/translations(音訊翻譯成英文)介面。 /v1/audio/speech一次性回傳完整音訊,不支援串流輸出,傳入stream_format: "sse"會回傳400。需要邊合成邊播放時,請用 Grok 串流語音合成。
基礎位址與鑑權:
Base URL: https://api.88api.ai/v1
Authorization: Bearer $API_KEYGrok 語音合成(grok-tts)
cURL
curl --fail-with-body https://api.88api.ai/v1/audio/speech \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-tts",
"input": "歡迎使用 88API 語音合成服務。",
"voice": "eve",
"language": "zh",
"response_format": "mp3"
}' \
--output speech.mp3成功回應是音訊二進位資料,不是 JSON,請直接寫入檔案。Windows 命令列直接用 -d 傳送非 ASCII 文字(如中文)容易出現亂碼,可以把請求內容存成 UTF-8 檔案,再用 --data-binary @request.json 送出。
請求欄位
| 欄位 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
model | string | 是 | — | grok-tts |
input | string | 是 | — | 要朗讀的文字,不能為空;可以插入下文的語氣標籤 |
voice | string | 否 | eve | 見下方音色表,不區分大小寫。OpenAI 的 alloy、nova 等音色名稱會回傳 400 |
response_format | string | 否 | mp3 | mp3、wav、pcm、mulaw、alaw;opus、aac、flac 會回傳 400 |
language | string | 否 | 自動辨識 | 語言代碼,如 zh、en、ja、ko、fr、ru、vi、pt-BR。固定語言比自動辨識更穩定 |
speed | number | 否 | 1.0 | 語速倍率,範圍 0.7–1.5,超出回傳 400 |
sample_rate | integer | 否 | 24000 | 8000、16000、22050、24000、44100、48000,其他值回傳 400 |
bit_rate | integer | 否 | 128000 | 僅 MP3 生效:32000、64000、96000、128000、192000 |
text_normalization | boolean | 否 | false | 為 true 時先把數字、縮寫、符號轉換成口語讀法再合成 |
replace | object | 否 | — | 發音替換表,例如 {"nginx": "engine x"},鍵為原文、值為讀法 |
sample_rate、bit_rate、text_normalization、replace 是 Grok 的擴充欄位,OpenAI SDK 中透過 extra_body 傳入。instructions 欄位對 grok-tts 不生效,語氣請用語氣標籤控制。
輸出格式
response_format | Content-Type | 說明 |
|---|---|---|
mp3 | audio/mpeg | 預設 24 kHz、128 kbps,可直接播放 |
wav | audio/wav | 16-bit 單聲道,適合後製編輯 |
pcm | audio/pcm | 16-bit 單聲道原始 PCM,無檔頭,需依取樣率解析 |
mulaw | audio/basic | G.711 μ-law,電話情境,常搭配 sample_rate: 8000 |
alaw | audio/alaw | G.711 A-law,電話情境,常搭配 sample_rate: 8000 |
pcm、mulaw、alaw 無法在瀏覽器中直接播放,網頁播放請用 mp3 或 wav。
音色
所有音色都能朗讀任何支援的語言,名稱不區分大小寫。風格描述來自 xAI 官方音色表,建議用自己的文案試聽 2–3 個後再固定。
| 音色 | 風格 | 適用情境 |
|---|---|---|
eve | 活力、明快,英式口音(預設) | 通用 |
ara | 溫暖、友善 | 通用 |
rex | 自信、清晰 | 通用 |
sal | 平穩、均衡 | 通用 |
leo | 權威、有力,英式口音 | 通用 |
carina | 柔和、富同理心、舒緩 | 健康、客服 |
zagan | 有力、戲劇化 | 角色、旁白 |
helix | 大膽、富有衝勁 | 解說、Podcast |
orion | 渾厚、電影感 | 旁白、有聲書 |
luna | 溫柔、耐心 | 教育、助理 |
iris | 友善、開朗 | 銷售、客服 |
altair | 優雅、精緻 | 廣告、旁白 |
zenith | 幹練、專注 | 銷售、廣告 |
perseus | 穩重、可信 | 廣告、旁白 |
helios | 開朗、充滿活力 | 助理、健康 |
lux | 沉穩、睿智 | 健康、旁白 |
kepler | 富有創意、有感染力 | 廣告、Podcast |
rigel | 精準、專業,澳洲口音 | 助理、客服 |
cosmo | 明亮、好奇、易懂 | 教育、Podcast |
celeste | 體貼、令人安心 | 客服、助理 |
ursa | 友善、溫暖、可靠 | 助理、Podcast |
sirius | 機智、俏皮 | 解說、角色 |
lumen | 溫暖、表達清晰 | 教育、廣告 |
castor | 親和、隨性 | 銷售、客服 |
naksh | 溫暖、睿智,印度口音 | 助理、客服 |
atlas | 自信、有掌控感 | 銷售、助理 |
aurora | 平靜、穩定 | 客服、助理 |
liora | 平和、踏實 | 健康、助理 |
不在上表中的音色名稱會回傳 400,錯誤訊息中會列出可用音色。
語氣標籤
在 input 中插入標籤可以控制停頓、笑聲、耳語等表達,完整說明見 xAI 官方文件。
| 類型 | 標籤 |
|---|---|
| 插入式(放在要發聲的位置) | [pause] [long-pause] [laugh] [chuckle] [giggle] [cry] [sigh] [breath] [inhale] [exhale] [tsk] [tongue-click] [lip-smack] [hum-tune] |
| 包裹式(成對包住一段文字) | <whisper> <soft> <loud> <build-intensity> <decrease-intensity> <higher-pitch> <lower-pitch> <slow> <fast> <emphasis> <sing-song> <singing> |
{
"model": "grok-tts",
"voice": "eve",
"input": "我推開門,[pause] 它就在那兒。[laugh] <whisper>這是個祕密。</whisper> <slow><soft>晚安。</soft></slow>"
}包裹式標籤必須成對出現,可以巢狀使用;整句包裹比只包一兩個字效果更自然。
Python(OpenAI SDK)
from openai import OpenAI
client = OpenAI(
api_key="YOUR_88API_KEY",
base_url="https://api.88api.ai/v1",
)
with client.audio.speech.with_streaming_response.create(
model="grok-tts",
voice="eve",
input="歡迎使用 88API 語音合成服務。",
response_format="mp3",
extra_body={"language": "zh", "sample_rate": 44100},
) as response:
response.stream_to_file("speech.mp3")Node.js(OpenAI SDK)
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.API_KEY,
baseURL: "https://api.88api.ai/v1",
});
const speech = await client.audio.speech.create({
model: "grok-tts",
voice: "ara",
input: "Hello from 88API. [laugh] <whisper>This part is a secret.</whisper>",
response_format: "wav",
});
fs.writeFileSync("speech.wav", Buffer.from(await speech.arrayBuffer()));Grok 串流語音合成(WebSocket)
適合大型語言模型一邊產生文字一邊朗讀、需要盡快開始播放的情境:文字可以分多次傳送,音訊邊合成邊回傳,第一段音訊通常在 0.3 秒左右到達。模型、音色、語氣標籤和價格與 grok-tts 相同。
連線
wss://api.88api.ai/v1/tts?model=grok-tts&voice=eve&codec=mp3&language=zh
Authorization: Bearer $API_KEY參數都放在連線位址的查詢字串中:
| 參數 | 必填 | 預設值 | 說明 |
|---|---|---|---|
model | 是 | — | grok-tts |
voice | 否 | eve | 見上方音色表 |
codec | 否 | mp3 | mp3、wav、pcm、mulaw(也可寫 ulaw)、alaw;opus、aac、flac 不支援 |
language | 否 | 自動辨識 | 語言代碼,如 zh、en、ja |
sample_rate | 否 | 24000 | 8000、16000、22050、24000、44100、48000 |
bit_rate | 否 | 128000 | 僅 MP3 生效:32000、64000、96000、128000、192000 |
speed | 否 | 1.0 | 語速倍率,範圍 0.7–1.5 |
text_normalization | 否 | false | true 或 false;為 true 時先把數字、縮寫、符號轉換成口語讀法再合成 |
訊息
連線建立後,雙方都傳送 JSON 文字訊息:
| 方向 | 訊息 | 說明 |
|---|---|---|
| 用戶端傳送 | {"type": "text.delta", "delta": "..."} | 追加要朗讀的文字,可以連續傳送多次 |
| 用戶端傳送 | {"type": "text.done"} | 這一段文字已傳送完畢 |
| 服務端回傳 | audio.delta | delta 是 Base64 編碼的音訊片段,依收到的順序串接即可得到完整音訊 |
| 服務端回傳 | audio.done | 這一段的音訊已全部回傳 |
| 服務端回傳 | error | 這一段合成失敗,詳情在訊息中 |
實際回傳範例:
{"type": "audio.delta", "delta": "//PExABLjDncBN4ZECBPfcTHl40IKQ..."}
{"type": "audio.done", "trace_id": "a52a926b-726f-439c-bbeb-5d741dd497ad"}- 收到
audio.done後連線仍然保持,可以繼續傳送下一段的text.delta和text.done,不必重新連線。 - 依實際合成出音訊的段落的文字字元數計費,與
grok-tts同價;合成失敗的段落和沒有傳送文字的連線不計費。 - 只支援 JSON 文字訊息,不要傳送二進位訊框。
- 參數在建立連線前校驗:
voice不在音色表中(包括 OpenAI 的音色名稱),或codec、sample_rate、speed等取值無效時,交握直接回傳 HTTP400,不會建立 WebSocket 連線,錯誤訊息會說明可用的取值。
Python
需要 websockets 14 以上版本(pip install websockets)。
import asyncio
import base64
import json
import websockets
API_KEY = "YOUR_88API_KEY"
URL = "wss://api.88api.ai/v1/tts?model=grok-tts&voice=eve&codec=mp3&language=zh"
async def main():
async with websockets.connect(
URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
) as ws:
segments = [
["歡迎使用 88API ", "串流語音合成,", "文字邊產生邊朗讀。"],
["同一個連線可以繼續合成下一段。"],
]
for i, pieces in enumerate(segments):
for text in pieces:
await ws.send(json.dumps({"type": "text.delta", "delta": text}))
await ws.send(json.dumps({"type": "text.done"}))
with open(f"part{i + 1}.mp3", "wb") as f:
async for message in ws:
event = json.loads(message)
if event["type"] == "audio.delta":
f.write(base64.b64decode(event["delta"]))
elif event["type"] == "audio.done":
break
elif event["type"] == "error":
raise RuntimeError(event)
asyncio.run(main())Node.js
使用 ws 函式庫(npm install ws)。
import fs from "node:fs";
import WebSocket from "ws";
const url = "wss://api.88api.ai/v1/tts?model=grok-tts&voice=ara&codec=mp3&language=zh";
const ws = new WebSocket(url, {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const chunks = [];
ws.on("open", () => {
for (const delta of ["我推開門,", "[pause] 它就在那兒。", "<whisper>這是個祕密。</whisper>"]) {
ws.send(JSON.stringify({ type: "text.delta", delta }));
}
ws.send(JSON.stringify({ type: "text.done" }));
});
ws.on("message", (data) => {
const event = JSON.parse(data.toString());
if (event.type === "audio.delta") {
chunks.push(Buffer.from(event.delta, "base64"));
} else if (event.type === "audio.done") {
fs.writeFileSync("speech.mp3", Buffer.concat(chunks));
ws.close();
} else if (event.type === "error") {
console.error(event);
ws.close();
}
});Grok 語音轉文字(grok-stt)
cURL
用 multipart/form-data 上傳音訊。讓 cURL 或 SDK 自動產生 multipart 邊界,不要手寫 Content-Type: multipart/form-data 請求標頭。
curl --fail-with-body https://api.88api.ai/v1/audio/transcriptions \
-H "Authorization: Bearer $API_KEY" \
-F "model=grok-stt" \
-F "language=zh" \
-F "keyterm=88API" \
-F "file=@./meeting.mp3"回應:
{
"text": "欢迎使用88API语音合成服务,今天是2026年10月17日。"
}中文辨識結果為簡體中文。
請求欄位
| 欄位 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
file | file | 是 | — | 音訊或影片檔案,支援 mp3、wav、ogg、opus、flac、aac、m4a、mp4、mkv,瀏覽器錄製的 webm 也可以 |
model | string | 是 | — | grok-stt |
response_format | string | 否 | json | json、text、verbose_json;srt、vtt 會回傳 400 |
language | string | 否 | 自動辨識 | 語言代碼,如 zh、en、ja、yue(粵語);指定後辨識更穩定 |
format | boolean | 否 | false | 為 true 時把口語數字、金額等轉成書面寫法,需同時傳 language |
keyterm | string | 否 | — | 需要優先辨識的專有名詞,例如產品名稱、人名;可重複傳多次,每次一個詞。上例不加 keyterm 時「88API」可能被辨識成「巴巴API」 |
filler_words | boolean | 否 | false | 為 true 時保留「嗯」「呃」等語氣詞,預設會去掉 |
OpenAI 的 prompt、temperature、timestamp_granularities 對 grok-stt 不生效,會被忽略。需要讓模型認準專有名詞時,請用 keyterm。
回應格式
response_format | Content-Type | 內容 |
|---|---|---|
json | application/json | {"text": "..."} |
text | text/plain | 純文字 |
verbose_json | application/json | text、language、duration(秒),以及逐詞時間戳記 words(word、start、end) |
verbose_json 範例:
{
"task": "transcribe",
"language": "zh-cn",
"duration": 6.456,
"text": "欢迎使用88API语音合成服务,今天是2026年10月17日。",
"words": [
{ "word": "欢", "start": 0.1, "end": 0.261 },
{ "word": "迎", "start": 0.301, "end": 0.461 }
]
}Python(OpenAI SDK)
from openai import OpenAI
client = OpenAI(
api_key="YOUR_88API_KEY",
base_url="https://api.88api.ai/v1",
)
with open("meeting.mp3", "rb") as audio_file:
result = client.audio.transcriptions.create(
model="grok-stt",
file=audio_file,
language="zh",
response_format="verbose_json",
extra_body={"format": "true", "keyterm": "88API"},
)
print(result.text, result.duration)Node.js(OpenAI SDK)
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.API_KEY,
baseURL: "https://api.88api.ai/v1",
});
const transcription = await client.audio.transcriptions.create({
model: "grok-stt",
file: fs.createReadStream("meeting.mp3"),
language: "zh",
});
console.log(transcription.text);Grok 即時語音對話(grok-voice)
透過一條 WebSocket 連線與模型即時語音對話:傳送文字或麥克風音訊,模型直接用語音回覆,並同時提供文字稿。適合語音助理、電話客服、口說陪練等情境。
| 模型 | 說明 |
|---|---|
grok-voice-latest | 始終指向最新版本,目前是 grok-voice-3.0 |
grok-voice-3.0 | 固定版本 |
連線
wss://api.88api.ai/v1/realtime?model=grok-voice-latest
Authorization: Bearer $API_KEY事件協定與 xAI Realtime 一致。連線成功後,服務端先傳送 session.created 和 conversation.created,之後由用戶端設定工作階段並開始對話。
- 預設情況下,音訊以 Base64 編碼放在 JSON 事件中收發。也可以切換為二進位傳輸,原始音訊直接走 WebSocket 二進位訊框,見 二進位音訊傳輸。
- 瀏覽器的 WebSocket 無法設定
Authorization請求標頭,也不應在前端公開 API Key。請在你自己的服務端建立連線,再把音訊轉送給瀏覽器或 App。 - 音訊格式:輸入和輸出都是 PCM16(16-bit 小端序)、24 kHz、單聲道。
設定工作階段
{
"type": "session.update",
"session": {
"voice": "eve",
"instructions": "你是 88API 的語音助理,回答簡潔。",
"turn_detection": { "type": "server_vad" }
}
}| 欄位 | 說明 |
|---|---|
voice | 回覆使用的音色,與 grok-tts 的 28 個音色相同(見上方音色表),不區分大小寫,預設 ara |
instructions | 系統指令,設定角色、語氣、回答長度等 |
turn_detection | {"type": "server_vad"}:服務端偵測到你說完話後自動回覆;null(預設):需要手動提交音訊並請求回覆 |
voice不在音色表中(包括 OpenAI 的音色名稱)時,會收到error事件,error.param為session.voice。這次session.update整體不生效,連線保持,改正後重新傳送即可。session.updated不會回顯音色。目前音色只在連線時的session.created中顯示,例如預設的xai_ara。
用戶端事件
| 事件 | 說明 |
|---|---|
session.update | 設定音色、系統指令和輪次偵測 |
conversation.item.create | 傳送一則文字訊息(content 中的 input_text) |
response.create | 請求模型回覆 |
input_audio_buffer.append | 追加一段音訊,audio 為 Base64 編碼的 PCM16 資料,建議每次 100 ms 左右 |
input_audio_buffer.commit | 提交已追加的音訊,作為一則使用者訊息;turn_detection 為 null 時使用 |
傳送文字:
{"type": "conversation.item.create", "item": {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "用一句話介紹你自己。"}]}}
{"type": "response.create"}傳送語音:連續傳送 input_audio_buffer.append。開啟 server_vad 時,說完話後的一段靜音會觸發自動回覆;turn_detection 為 null 時,傳完音訊再傳送 input_audio_buffer.commit 和 response.create。
服務端事件
| 事件 | 說明 |
|---|---|
session.created、session.updated | 工作階段已建立、設定已生效 |
input_audio_buffer.speech_started / speech_stopped | server_vad 偵測到開始說話、停止說話 |
conversation.item.input_audio_transcription.completed | 使用者語音的辨識文字,在 transcript 中 |
response.output_audio.delta | 回覆音訊片段,delta 為 Base64 編碼的 PCM16 24 kHz 單聲道 |
response.output_audio_transcript.delta / .done | 回覆的文字稿,.done 中的 transcript 是完整文字 |
response.done | 本輪回覆結束 |
ping | 心跳,可以忽略 |
error | 錯誤,詳情在 error.message 和 error.code 中 |
依上面的工作階段設定傳送這則文字訊息,實際回傳(節錄):
{"type": "response.output_audio_transcript.delta", "delta": "我是 88API 的語音助理。"}
{"type": "response.output_audio.delta", "delta": "<Base64 音訊>"}
{"type": "response.output_audio_transcript.done", "transcript": "我是 88API 的語音助理。"}
{"type": "response.output_audio.done"}
{"type": "response.done", "response": {"status": "completed", "output": [{"type": "message", "role": "assistant", "content": [{"type": "audio", "transcript": "我是 88API 的語音助理。"}]}]}}計費
- 依通話時長計費:從連線建立到中斷按秒累計,沒有說話的閒置時間同樣計時,用完請及時關閉連線。價格見控制台模型廣場。
- 每則使用者文字訊息(帶
input_text的conversation.item.create)另計少量費用;語音輸入和模型的語音回覆不再單獨計費。 - 餘額或令牌額度不足 1 分鐘通話費用時,連線建立後會立即收到
error(code為insufficient_user_quota)並中斷。通話中餘額用完時,會在 30 秒內收到同樣的error,隨後連線以關閉碼1008中斷。
Python
需要 websockets 14 以上版本(pip install websockets)。下面的範例傳送一則文字訊息,把語音回覆儲存為 reply.wav:
import asyncio
import base64
import json
import wave
import websockets
API_KEY = "YOUR_88API_KEY"
URL = "wss://api.88api.ai/v1/realtime?model=grok-voice-latest"
async def main():
async with websockets.connect(
URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
) as ws:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"voice": "eve",
"instructions": "你是 88API 的語音助理,回答簡潔。",
"turn_detection": {"type": "server_vad"},
},
}))
await ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": "用一句話介紹你自己。"}],
},
}))
await ws.send(json.dumps({"type": "response.create"}))
audio = bytearray()
async for message in ws:
event = json.loads(message)
if event["type"] == "response.output_audio.delta":
audio += base64.b64decode(event["delta"])
elif event["type"] == "response.output_audio_transcript.done":
print("文字稿:", event["transcript"])
elif event["type"] == "response.done":
break
elif event["type"] == "error":
raise RuntimeError(event)
with wave.open("reply.wav", "wb") as f:
f.setnchannels(1)
f.setsampwidth(2)
f.setframerate(24000)
f.writeframes(bytes(audio))
asyncio.run(main())傳送語音時,把 24 kHz、16-bit、單聲道的音訊分段傳送。以上面開啟了 server_vad 的工作階段為例,可以取代傳送文字的兩則訊息:
with wave.open("question.wav", "rb") as f: # 24 kHz、16-bit、單聲道
pcm = f.readframes(f.getnframes())
pcm += b"\x00" * 48000 # 末尾補 1 秒靜音,讓 server_vad 判斷說話結束
for i in range(0, len(pcm), 4800): # 每次 100 ms
await ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": base64.b64encode(pcm[i:i + 4800]).decode(),
}))即時麥克風輸入時直接傳送擷取到的音訊即可,不需要補靜音。
Node.js
使用 ws 函式庫(npm install ws)。這個範例關閉 server_vad,傳送文字後手動請求回覆,並把回覆儲存為 reply.wav:
import fs from "node:fs";
import WebSocket from "ws";
const ws = new WebSocket("wss://api.88api.ai/v1/realtime?model=grok-voice-latest", {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const send = (event) => ws.send(JSON.stringify(event));
const chunks = [];
// 為 PCM16 24 kHz 單聲道資料加上 WAV 檔頭
function toWav(pcm, rate = 24000) {
const header = Buffer.alloc(44);
header.write("RIFF", 0);
header.writeUInt32LE(36 + pcm.length, 4);
header.write("WAVEfmt ", 8);
header.writeUInt32LE(16, 16);
header.writeUInt16LE(1, 20);
header.writeUInt16LE(1, 22);
header.writeUInt32LE(rate, 24);
header.writeUInt32LE(rate * 2, 28);
header.writeUInt16LE(2, 32);
header.writeUInt16LE(16, 34);
header.write("data", 36);
header.writeUInt32LE(pcm.length, 40);
return Buffer.concat([header, pcm]);
}
ws.on("open", () => {
send({
type: "session.update",
session: { voice: "rex", instructions: "用一句話回答。", turn_detection: null },
});
send({
type: "conversation.item.create",
item: {
type: "message",
role: "user",
content: [{ type: "input_text", text: "法國的首都是哪裡?" }],
},
});
send({ type: "response.create" });
});
ws.on("message", (data) => {
const event = JSON.parse(data.toString());
switch (event.type) {
case "response.output_audio.delta":
chunks.push(Buffer.from(event.delta, "base64"));
break;
case "response.output_audio_transcript.delta":
process.stdout.write(event.delta);
break;
case "response.done":
fs.writeFileSync("reply.wav", toWav(Buffer.concat(chunks)));
ws.close();
break;
case "error":
console.error(event.error);
ws.close();
break;
}
});二進位音訊傳輸
在 session.update 中把輸入和輸出的 transport 設為 "binary" 後,原始 PCM 音訊直接作為 WebSocket 二進位訊框收發,省去 Base64 編解碼:
{
"type": "session.update",
"session": {
"turn_detection": null,
"audio": {
"input": { "format": { "type": "audio/pcm", "rate": 24000 }, "transport": "binary" },
"output": { "format": { "type": "audio/pcm", "rate": 24000 }, "transport": "binary" }
}
}
}- 傳送:每個二進位訊框是一段 PCM16、24 kHz、單聲道的原始音訊,建議每個訊框 100 ms(4800 位元組),取代
input_audio_buffer.append。 - 接收:回覆音訊以二進位訊框回傳,不再有
response.output_audio.delta事件,依收到的順序拼接即可。 input_audio_buffer.commit、response.create等控制事件,以及session.updated、文字稿、response.done等服務端事件,仍然是 JSON 文字訊框。- 計費方式不變。
Python 範例:傳送一段語音提問,把語音回覆儲存為 reply.wav:
import asyncio
import json
import wave
import websockets
API_KEY = "YOUR_88API_KEY"
URL = "wss://api.88api.ai/v1/realtime?model=grok-voice-latest"
PCM = {"type": "audio/pcm", "rate": 24000}
async def main():
async with websockets.connect(
URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
) as ws:
await ws.send(json.dumps({
"type": "session.update",
"session": {
"voice": "eve",
"turn_detection": None,
"audio": {
"input": {"format": PCM, "transport": "binary"},
"output": {"format": PCM, "transport": "binary"},
},
},
}))
with wave.open("question.wav", "rb") as f: # 24 kHz、16-bit、單聲道
pcm = f.readframes(f.getnframes())
for i in range(0, len(pcm), 4800): # 每個訊框 100 ms,直接傳送原始 PCM
await ws.send(pcm[i:i + 4800])
await ws.send(json.dumps({"type": "input_audio_buffer.commit"}))
await ws.send(json.dumps({"type": "response.create"}))
audio = bytearray()
async for message in ws:
if isinstance(message, bytes): # 二進位訊框:回覆音訊
audio += message
continue
event = json.loads(message) # 文字訊框:控制事件
if event["type"] == "response.output_audio_transcript.done":
print("文字稿:", event["transcript"])
elif event["type"] == "response.done":
break
elif event["type"] == "error":
raise RuntimeError(event)
with wave.open("reply.wav", "wb") as f:
f.setnchannels(1)
f.setsampwidth(2)
f.setframerate(24000)
f.writeframes(bytes(audio))
asyncio.run(main())Gemini 語音合成
Gemini 語音合成目前只有 gemini-3.8-flash-tts,須使用 Gemini 原生介面呼叫,不支援 /v1/audio/speech(會回傳 500「模型沒有回傳音訊」,不扣費)。原 gemini-3.1-flash-tts、gemini-3.8-flash-lite-tts、gemini-2.5-flash-tts、gemini-2.5-pro-tts 已停止提供;需要 /v1/audio/speech 或串流音訊時,請使用 Grok 語音合成。
cURL
金鑰同樣是 88API 的 API 金鑰,可放在 x-goog-api-key 請求標頭中。
curl --fail-with-body "https://api.88api.ai/v1beta/models/gemini-3.8-flash-tts:generateContent" \
-H "x-goog-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{ "role": "user", "parts": [{ "text": "歡迎使用 88API 語音合成服務。<laugh> 今天天氣真好。" }] }],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } }
}
}
}'回應與下載
回應是 JSON,不包含音訊資料,而是在 candidates[0].content.parts[0].text 中回傳一個音訊下載連結,格式為 Markdown 連結(連結文字固定為簡體中文「生成音频」):
{
"candidates": [{
"content": {
"role": "model",
"parts": [{ "text": "[生成音频](https://example.com/contents/xxxxxxxx.wav)" }]
},
"finishReason": "STOP"
}]
}- 從文字中取出括號裡的網址下載即可,下載不需要 API 金鑰。音訊為 WAV 檔案(24 kHz、16-bit、單聲道)。
- 連結只保留幾個小時,過期後無法下載,請在拿到回應後立即下載保存。
- 依輸入與輸出 Token 計費,價格以控制台模型廣場顯示為準。
- 串流介面
POST /v1beta/models/gemini-3.8-flash-tts:streamGenerateContent?alt=sse可以呼叫,但不會分段回傳音訊:合成完成後會在一個事件中回傳同樣的下載連結。
朗讀規則
- 逐字朗讀:文字中的所有內容都會被讀出來。不要在文字裡寫「用歡快的語氣說:」之類的說明,否則這句話也會被朗讀。
- 語氣用文字中的角括號標籤控制,標籤本身不會被讀出來,例如
<laugh>(笑)、<short pause>(短停頓)、<whispers>(耳語)、<sigh>(嘆氣)。
音色
在 speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName 中指定,共 30 個預設音色。風格描述來自 Google 官方音色表;所有音色都能朗讀中文等多種語言。
| 音色 | 風格 | 性別 |
|---|---|---|
Achernar | 柔和 | 女聲 |
Achird | 友善 | 男聲 |
Algenib | 沙啞 | 男聲 |
Algieba | 圓潤 | 男聲 |
Alnilam | 堅定 | 男聲 |
Aoede | 輕快 | 女聲 |
Autonoe | 明亮 | 女聲 |
Callirrhoe | 隨和 | 女聲 |
Charon | 知性 | 男聲 |
Despina | 圓潤 | 女聲 |
Enceladus | 氣聲 | 男聲 |
Erinome | 清晰 | 女聲 |
Fenrir | 興奮 | 男聲 |
Gacrux | 成熟 | 女聲 |
Iapetus | 清晰 | 男聲 |
Kore | 堅定 | 女聲 |
Laomedeia | 歡快 | 女聲 |
Leda | 年輕 | 女聲 |
Orus | 堅定 | 男聲 |
Puck | 歡快 | 男聲 |
Pulcherrima | 直率 | 女聲 |
Rasalgethi | 知性 | 男聲 |
Sadachbia | 活潑 | 男聲 |
Sadaltager | 博學 | 男聲 |
Schedar | 平穩 | 男聲 |
Sulafat | 溫暖 | 女聲 |
Umbriel | 隨和 | 男聲 |
Vindemiatrix | 溫柔 | 女聲 |
Zephyr | 明亮 | 女聲 |
Zubenelgenubi | 隨意 | 男聲 |
沒有把握時可以先試 Kore(女聲)和 Charon(男聲)。音色與語言的更新以 Google Gemini-TTS 官方文件 為準。
雙人對話
把 speechConfig 中的 voiceConfig 換成 multiSpeakerVoiceConfig,為最多 2 個說話人分別指定音色。文字每行只寫「名字: 台詞」,不要加「TTS the following conversation…」這類說明(會被讀出來):
{
"contents": [{
"role": "user",
"parts": [{ "text": "Joe: How's it going today Jane?\nJane: Not too bad, how about you?" }]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"multiSpeakerVoiceConfig": {
"speakerVoiceConfigs": [
{ "speaker": "Joe", "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Charon" } } },
{ "speaker": "Jane", "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } } }
]
}
}
}
}回傳方式與單人相同,也是一個 WAV 下載連結。
Gemini 語音轉文字
| 模型 | 說明 |
|---|---|
gemini-3-stt | 推薦,適合一般轉寫、會議記錄和字幕 |
gemini-3.5-stt | 適合更複雜的音訊,單價較高 |
gemini-3.5-transcribe | 專用轉寫模型,自動辨識 85 種以上語言,單次最長約 1 小時音訊,速度快 |
三個模型的呼叫方式相同,以下範例換成其他模型名稱即可,gemini-3.5-transcribe 的不同之處見 gemini-3.5-transcribe。支援三種呼叫方式:上傳檔案到 /v1/audio/transcriptions(推薦)、在對話介面中傳入音訊,或使用 Gemini 原生介面。
上傳檔案轉寫(推薦)
與 grok-stt 一樣使用 multipart/form-data,不要手寫 Content-Type: multipart/form-data 請求標頭。
curl --fail-with-body https://api.88api.ai/v1/audio/transcriptions \
-H "Authorization: Bearer $API_KEY" \
-F "model=gemini-3-stt" \
-F "language=zh" \
-F "file=@./meeting.mp3"回應:
{
"text": "欢迎使用88API语音合成服务,今天是2026年10月17日。"
}| 欄位 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
file | file | 是 | — | 音訊檔案,常見格式如 mp3、wav、m4a、ogg、flac 皆可,最大 25 MB |
model | string | 是 | — | gemini-3-stt、gemini-3.5-stt 或 gemini-3.5-transcribe |
response_format | string | 否 | json | json({"text": "..."})、text(純文字)、verbose_json(另含 task、language、duration);srt、vtt 會回傳 400 |
language | string | 否 | 自動辨識 | 語言代碼,如 zh、en、yue(粵語) |
prompt | string | 否 | — | 情境、人名、術語等提示,幫助辨識;對 gemini-3.5-transcribe 無效 |
verbose_json 不含逐詞時間戳記(words)或分段(segments);需要逐詞時間戳記請用 grok-stt,或 gemini-3.5-transcribe 的原生介面。檔案超過 25 MB 會回傳 400,請壓縮(例如轉成 16 kHz 單聲道 MP3)或分段後再轉寫。
Python(OpenAI SDK):
from openai import OpenAI
client = OpenAI(
api_key="YOUR_88API_KEY",
base_url="https://api.88api.ai/v1",
)
with open("meeting.mp3", "rb") as audio_file:
result = client.audio.transcriptions.create(
model="gemini-3-stt",
file=audio_file,
language="zh",
)
print(result.text)對話介面(音訊輸入)
把音訊以 Base64 放進對話訊息,依你的文字指令輸出轉寫結果。可以在指令中說明情境、人名和術語,幫助模型準確辨識。
cURL
先把音訊轉成 Base64,再放進 input_audio:
AUDIO_B64=$(base64 < meeting.mp3 | tr -d '\n')
cat > request.json <<EOF
{
"model": "gemini-3-stt",
"messages": [{
"role": "user",
"content": [
{ "type": "text", "text": "請把這段音訊轉寫成文字,只輸出轉寫結果。" },
{ "type": "input_audio", "input_audio": { "data": "$AUDIO_B64", "format": "mp3" } }
]
}]
}
EOF
curl --fail-with-body https://api.88api.ai/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
--data-binary @request.json轉寫結果在 choices[0].message.content。format 填音訊格式,如 mp3、wav。
Python(OpenAI SDK)
import base64
from openai import OpenAI
client = OpenAI(
api_key="YOUR_88API_KEY",
base_url="https://api.88api.ai/v1",
)
with open("meeting.mp3", "rb") as f:
audio_b64 = base64.b64encode(f.read()).decode()
completion = client.chat.completions.create(
model="gemini-3-stt",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "請把這段音訊轉寫成文字,只輸出轉寫結果。"},
{"type": "input_audio", "input_audio": {"data": audio_b64, "format": "mp3"}},
],
}],
)
print(completion.choices[0].message.content)Node.js(OpenAI SDK)
import fs from "node:fs";
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.API_KEY,
baseURL: "https://api.88api.ai/v1",
});
const audio = fs.readFileSync("meeting.mp3").toString("base64");
const completion = await client.chat.completions.create({
model: "gemini-3-stt",
messages: [{
role: "user",
content: [
{ type: "text", text: "請把這段音訊轉寫成文字,只輸出轉寫結果。" },
{ type: "input_audio", input_audio: { data: audio, format: "mp3" } },
],
}],
});
console.log(completion.choices[0].message.content);Gemini 原生介面
{
"contents": [{
"role": "user",
"parts": [
{ "text": "請把這段音訊轉寫成文字,只輸出轉寫結果。" },
{ "inlineData": { "mimeType": "audio/wav", "data": "<Base64 音訊>" } }
]
}]
}傳送到 POST https://api.88api.ai/v1beta/models/gemini-3-stt:generateContent,請求標頭帶上 x-goog-api-key: $API_KEY。
對話介面和原生介面把音訊以 Base64 放在請求內容裡,適合較短的錄音;檔案較大時請用上傳檔案轉寫。已停用的 gemini-2.5-stt、gemini-3.6-stt 請改用 gemini-3-stt、gemini-3.5-stt 或 grok-stt。
gemini-3.5-transcribe
專用轉寫模型,只需要音訊,不需要也不接受文字指令:
/v1/audio/transcriptions:language填 BCP-47 語言代碼,如zh、en、yue,無效代碼回傳400;prompt無效。模型不回傳辨識出的語言,verbose_json的language是你傳入的值,沒傳時為空字串。- 對話介面:訊息中的文字會被忽略,也不計費,只傳送
input_audio即可;帶system訊息或reasoning_effort會回傳400。 - 原生介面:可以用
generationConfig.audioTranscriptionConfig指定語言、自訂詞彙、說話人區分和逐詞時間戳記。 - 不提供即時串流轉寫。
原生介面範例:
curl --fail-with-body "https://api.88api.ai/v1beta/models/gemini-3.5-transcribe:generateContent" \
-H "x-goog-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{
"role": "user",
"parts": [{ "inlineData": { "mimeType": "audio/wav", "data": "<Base64 音訊>" } }]
}],
"generationConfig": {
"audioTranscriptionConfig": { "diarization": true, "wordTimestamp": true }
}
}'audioTranscriptionConfig 欄位 | 類型 | 說明 |
|---|---|---|
languageCodes | string[] | 音訊語言,BCP-47 代碼,如 ["zh"];不傳時自動辨識 |
customVocabulary | string[] | 需要優先辨識的專有名詞,如 ["88API"];這些詞計入輸入用量 |
diarization | boolean | 區分說話人,每段結果帶 speakerLabel(實驗功能) |
wordTimestamp | boolean | 回傳逐詞時間戳記 words(實驗功能) |
mode | string | SMART:智慧轉寫模式,處理時間較長;不能與 diarization、wordTimestamp 同時使用,否則回傳 400 |
對一段雙人對話的實際回傳(candidates[0].content.parts,節錄):
[
{
"text": "How's it going today, Jane?",
"audioTranscription": {
"text": "How's it going today, Jane?",
"speakerLabel": "spk:0",
"words": [
{ "word": "How's", "startOffset": "0.200s", "endOffset": "0.300s" },
{ "word": "it", "startOffset": "0.300s", "endOffset": "0.400s" }
]
}
},
{
"text": "Not too bad. How about you?",
"audioTranscription": {
"text": "Not too bad. How about you?",
"speakerLabel": "spk:1",
"words": [
{ "word": "Not", "startOffset": "2.100s", "endOffset": "2.200s" }
]
}
}
]不開啟說話人區分時,整段轉寫結果在 parts[0].text 中。說話人區分和逐詞時間戳記是實驗功能:中英混合的音訊可能遺漏非主要語言的片段,需要完整文字時請關閉這兩項。
常見錯誤
| 狀態碼 | 常見原因 | 處理建議 |
|---|---|---|
400 | 缺少 input / file、音色名稱不在音色表中(包括 OpenAI 的音色名稱)、格式或取樣率不支援、speed 超出範圍、文字過長、上傳檔案超過 25 MB | 依錯誤提示和本文欄位說明修改請求 |
400 | 用對話、Responses 或 Messages 介面呼叫了語音模型 | 改用本文對應的介面 |
400 | 文字內容被安全策略攔截(PROHIBITED_CONTENT) | 修改文字後重試,重複送出相同內容無法解決 |
401 | API Key 缺失或無效 | 檢查 Bearer Token,不要在瀏覽器前端公開金鑰 |
429 | 速率、額度或容量限制 | 指數退避重試,並檢查帳戶餘額 |
500 / 502 / 503 | 服務端或上游臨時異常 | 有限次數重試,仍失敗時攜帶請求 ID 聯絡支援 |
錯誤回應中的 request id 是排查依據,請在日誌中保留;不要記錄 API Key、私密音訊或敏感轉寫內容。