88API88API
使用指南AI 應用API 文件幫助支援
音訊(Audio)

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-ttsPOST /v1/audio/speech輸入字元數
串流語音合成grok-ttsWebSocket /v1/tts輸入字元數
即時語音對話grok-voice-latest、grok-voice-3.0WebSocket /v1/realtime通話時長
語音合成gemini-3.8-flash-ttsGemini 原生 generateContent(回傳音訊下載連結)Token
語音轉文字grok-sttPOST /v1/audio/transcriptions音訊時長
語音轉文字gemini-3-stt、gemini-3.5-stt、gemini-3.5-transcribePOST /v1/audio/transcriptions、POST /v1/chat/completions(音訊輸入),或 Gemini 原生 generateContentToken
  • 價格以控制台模型廣場顯示為準。令牌分組選擇「语音模型」(控制台顯示的分組名稱)或自動分組。
  • 語音模型只能使用上表中的介面。用對話、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_KEY

Grok 語音合成(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 送出。

請求欄位

欄位類型必填預設值說明
modelstring是—grok-tts
inputstring是—要朗讀的文字,不能為空;可以插入下文的語氣標籤
voicestring否eve見下方音色表,不區分大小寫。OpenAI 的 alloy、nova 等音色名稱會回傳 400
response_formatstring否mp3mp3、wav、pcm、mulaw、alaw;opus、aac、flac 會回傳 400
languagestring否自動辨識語言代碼,如 zh、en、ja、ko、fr、ru、vi、pt-BR。固定語言比自動辨識更穩定
speednumber否1.0語速倍率,範圍 0.7–1.5,超出回傳 400
sample_rateinteger否240008000、16000、22050、24000、44100、48000,其他值回傳 400
bit_rateinteger否128000僅 MP3 生效:32000、64000、96000、128000、192000
text_normalizationboolean否false為 true 時先把數字、縮寫、符號轉換成口語讀法再合成
replaceobject否—發音替換表,例如 {"nginx": "engine x"},鍵為原文、值為讀法

sample_rate、bit_rate、text_normalization、replace 是 Grok 的擴充欄位,OpenAI SDK 中透過 extra_body 傳入。instructions 欄位對 grok-tts 不生效,語氣請用語氣標籤控制。

輸出格式

response_formatContent-Type說明
mp3audio/mpeg預設 24 kHz、128 kbps,可直接播放
wavaudio/wav16-bit 單聲道,適合後製編輯
pcmaudio/pcm16-bit 單聲道原始 PCM,無檔頭,需依取樣率解析
mulawaudio/basicG.711 μ-law,電話情境,常搭配 sample_rate: 8000
alawaudio/alawG.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否mp3mp3、wav、pcm、mulaw(也可寫 ulaw)、alaw;opus、aac、flac 不支援
language否自動辨識語言代碼,如 zh、en、ja
sample_rate否240008000、16000、22050、24000、44100、48000
bit_rate否128000僅 MP3 生效:32000、64000、96000、128000、192000
speed否1.0語速倍率,範圍 0.7–1.5
text_normalization否falsetrue 或 false;為 true 時先把數字、縮寫、符號轉換成口語讀法再合成

訊息

連線建立後,雙方都傳送 JSON 文字訊息:

方向訊息說明
用戶端傳送{"type": "text.delta", "delta": "..."}追加要朗讀的文字,可以連續傳送多次
用戶端傳送{"type": "text.done"}這一段文字已傳送完畢
服務端回傳audio.deltadelta 是 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 等取值無效時,交握直接回傳 HTTP 400,不會建立 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日。"
}

中文辨識結果為簡體中文。

請求欄位

欄位類型必填預設值說明
filefile是—音訊或影片檔案,支援 mp3、wav、ogg、opus、flac、aac、m4a、mp4、mkv,瀏覽器錄製的 webm 也可以
modelstring是—grok-stt
response_formatstring否jsonjson、text、verbose_json;srt、vtt 會回傳 400
languagestring否自動辨識語言代碼,如 zh、en、ja、yue(粵語);指定後辨識更穩定
formatboolean否false為 true 時把口語數字、金額等轉成書面寫法,需同時傳 language
keytermstring否—需要優先辨識的專有名詞,例如產品名稱、人名;可重複傳多次,每次一個詞。上例不加 keyterm 時「88API」可能被辨識成「巴巴API」
filler_wordsboolean否false為 true 時保留「嗯」「呃」等語氣詞,預設會去掉

OpenAI 的 prompt、temperature、timestamp_granularities 對 grok-stt 不生效,會被忽略。需要讓模型認準專有名詞時,請用 keyterm。

回應格式

response_formatContent-Type內容
jsonapplication/json{"text": "..."}
texttext/plain純文字
verbose_jsonapplication/jsontext、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_stoppedserver_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日。"
}
欄位類型必填預設值說明
filefile是—音訊檔案,常見格式如 mp3、wav、m4a、ogg、flac 皆可,最大 25 MB
modelstring是—gemini-3-stt、gemini-3.5-stt 或 gemini-3.5-transcribe
response_formatstring否jsonjson({"text": "..."})、text(純文字)、verbose_json(另含 task、language、duration);srt、vtt 會回傳 400
languagestring否自動辨識語言代碼,如 zh、en、yue(粵語)
promptstring否—情境、人名、術語等提示,幫助辨識;對 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 欄位類型說明
languageCodesstring[]音訊語言,BCP-47 代碼,如 ["zh"];不傳時自動辨識
customVocabularystring[]需要優先辨識的專有名詞,如 ["88API"];這些詞計入輸入用量
diarizationboolean區分說話人,每段結果帶 speakerLabel(實驗功能)
wordTimestampboolean回傳逐詞時間戳記 words(實驗功能)
modestringSMART:智慧轉寫模式,處理時間較長;不能與 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)修改文字後重試,重複送出相同內容無法解決
401API Key 缺失或無效檢查 Bearer Token,不要在瀏覽器前端公開金鑰
429速率、額度或容量限制指數退避重試,並檢查帳戶餘額
500 / 502 / 503服務端或上游臨時異常有限次數重試,仍失敗時攜帶請求 ID 聯絡支援

錯誤回應中的 request id 是排查依據,請在日誌中保留;不要記錄 API Key、私密音訊或敏感轉寫內容。