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 传中文容易乱码,可以把请求体存成 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大胆、富有冲劲解说、播客
orion浑厚、电影感旁白、有声书
luna温柔、耐心教育、助手
iris友好、开朗销售、客服
altair优雅、精致广告、旁白
zenith干练、专注销售、广告
perseus稳重、可信广告、旁白
helios开朗、充满活力助手、健康
lux沉稳、睿智健康、旁白
kepler富有创意、有感染力广告、播客
rigel精准、专业,澳洲口音助手、客服
cosmo明亮、好奇、易懂教育、播客
celeste体贴、令人安心客服、助手
ursa友好、温暖、可靠助手、播客
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、私密音频或敏感转写内容。