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 传中文容易乱码,可以把请求体存成 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 | 大胆、富有冲劲 | 解说、播客 |
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 | 否 | 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、私密音频或敏感转写内容。