88API Speech APIs: TTS & STT
Integration guide for Grok and Gemini speech models: /v1/audio/speech text to speech, WebSocket streaming text to speech, Grok realtime voice conversation, /v1/audio/transcriptions and audio chat transcription, with all voices, output formats, request fields, cURL, OpenAI SDK, Python and Node.js examples.
88API offers two families of speech models: Grok and Gemini. Text to speech (TTS) and speech to text (STT) use different models, endpoints and fields, so choose from the table below.
Models and endpoints
| Capability | Models | Endpoint | Billed by |
|---|---|---|---|
| Text to speech | grok-tts | POST /v1/audio/speech | Input characters |
| Streaming text to speech | grok-tts | WebSocket /v1/tts | Input characters |
| Realtime voice conversation | grok-voice-latest, grok-voice-3.0 | WebSocket /v1/realtime | Call duration |
| Text to speech | gemini-3.8-flash-tts | Gemini native generateContent (returns an audio download link) | Tokens |
| Speech to text | grok-stt | POST /v1/audio/transcriptions | Audio duration |
| Speech to text | gemini-3-stt, gemini-3.5-stt, gemini-3.5-transcribe | POST /v1/audio/transcriptions, POST /v1/chat/completions (audio input), or Gemini native generateContent | Tokens |
- Prices are as shown in the model marketplace in the console. For the token group, choose
语音模型(the group name as shown in the console) or auto grouping. - Speech models only work with the endpoints in the table above. Calling a TTS model or
grok-sttthrough the Chat, Responses or Messages endpoint returns400with a hint to use the correct endpoint. - The
/v1/audio/translationsendpoint (translating audio into English) is not provided. /v1/audio/speechreturns the complete audio in one response. Streaming is not supported;stream_format: "sse"returns400. To play audio while it is being synthesized, use Grok streaming text to speech.
Base URL and authentication:
Base URL: https://api.88api.ai/v1
Authorization: Bearer $API_KEYGrok text to speech (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": "Welcome to the 88API speech service.",
"voice": "eve",
"language": "en",
"response_format": "mp3"
}' \
--output speech.mp3A successful response is binary audio, not JSON; write it directly to a file. On Windows, passing non-ASCII text with -d can garble it; save the body as a UTF-8 file and send it with --data-binary @request.json.
Request fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | Yes | — | grok-tts |
input | string | Yes | — | Text to read aloud; must not be empty. You can insert the speech tags described below |
voice | string | No | eve | See the voice table below; case-insensitive. OpenAI voice names such as alloy and nova return 400 |
response_format | string | No | mp3 | mp3, wav, pcm, mulaw, alaw; opus, aac and flac return 400 |
language | string | No | Auto-detected | Language code, such as zh, en, ja, ko, fr, ru, vi, pt-BR. A fixed language is more stable than auto-detection |
speed | number | No | 1.0 | Speed multiplier, range 0.7–1.5; values outside it return 400 |
sample_rate | integer | No | 24000 | 8000, 16000, 22050, 24000, 44100, 48000; other values return 400 |
bit_rate | integer | No | 128000 | MP3 only: 32000, 64000, 96000, 128000, 192000 |
text_normalization | boolean | No | false | When true, numbers, abbreviations and symbols are converted to their spoken form before synthesis |
replace | object | No | — | Pronunciation replacement map, e.g. {"nginx": "engine x"}; keys are the original text, values are how to read it |
sample_rate, bit_rate, text_normalization and replace are Grok extension fields; pass them through extra_body in the OpenAI SDK. The instructions field has no effect on grok-tts; use speech tags to control delivery.
Output formats
response_format | Content-Type | Description |
|---|---|---|
mp3 | audio/mpeg | 24 kHz, 128 kbps by default; plays directly |
wav | audio/wav | 16-bit mono; suited to post-editing |
pcm | audio/pcm | 16-bit mono raw PCM with no header; parse it by sample rate |
mulaw | audio/basic | G.711 μ-law for telephony; usually paired with sample_rate: 8000 |
alaw | audio/alaw | G.711 A-law for telephony; usually paired with sample_rate: 8000 |
pcm, mulaw and alaw cannot be played directly in a browser; use mp3 or wav for web playback.
Voices
Every voice can read any supported language, and names are case-insensitive. Style descriptions come from the official xAI voice list. Audition 2–3 voices with your own script before fixing one.
| Voice | Style | Use cases |
|---|---|---|
eve | Energetic and upbeat, British accent (default) | General |
ara | Warm and friendly | General |
rex | Confident and clear | General |
sal | Smooth and balanced | General |
leo | Authoritative and strong, British accent | General |
carina | Soft, empathetic, soothing | Wellness, Support |
zagan | Powerful, dramatic | Characters, Narration |
helix | Bold, dynamic, adrenaline-fueled | Commentary, Podcast |
orion | Rich, cinematic, resonant | Narration, Audiobooks |
luna | Gentle, patient, nurturing | Education, Assistant |
iris | Friendly, upbeat, charming | Sales, Support |
altair | Elegant, refined | Advertising, Narration |
zenith | Sharp, focused, driven | Sales, Advertising |
perseus | Strong, confident, trustworthy | Advertising, Narration |
helios | Upbeat, energetic, versatile | Assistant, Wellness |
lux | Grounded, calm, quietly wise | Wellness, Narration |
kepler | Inventive, charismatic | Advertising, Podcast |
rigel | Precise, professional, Australian accent | Assistant, Support |
cosmo | Bright, curious, easy to follow | Education, Podcast |
celeste | Compassionate, reassuring | Support, Assistant |
ursa | Friendly, warm, steadfast | Assistant, Podcast |
sirius | Quick-witted, playful | Commentary, Characters |
lumen | Warm, articulate, engaging | Education, Advertising |
castor | Charismatic, down-to-earth, easygoing | Sales, Support |
naksh | Warm, thoughtful, wise, Indian accent | Assistant, Support |
atlas | Confident, commanding, reassuring | Sales, Assistant |
aurora | Serene, steady | Support, Assistant |
liora | Calm, grounded | Wellness, Assistant |
A voice name that is not in the table above returns 400, and the error message lists the available voices.
Speech tags
Insert tags into input to control pauses, laughter, whispering and other expression. See the official xAI documentation for details.
| Type | Tags |
|---|---|
| Inline (placed where the sound should occur) | [pause] [long-pause] [laugh] [chuckle] [giggle] [cry] [sigh] [breath] [inhale] [exhale] [tsk] [tongue-click] [lip-smack] [hum-tune] |
| Wrapping (a pair enclosing a span of text) | <whisper> <soft> <loud> <build-intensity> <decrease-intensity> <higher-pitch> <lower-pitch> <slow> <fast> <emphasis> <sing-song> <singing> |
{
"model": "grok-tts",
"voice": "eve",
"input": "I opened the door, [pause] and there it was. [laugh] <whisper>It's a secret.</whisper> <slow><soft>Good night.</soft></slow>"
}Wrapping tags must come in pairs and can be nested; wrapping a whole sentence sounds more natural than wrapping just a word or two.
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="Welcome to the 88API speech service.",
response_format="mp3",
extra_body={"language": "en", "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 streaming text to speech (WebSocket)
Designed for reading text aloud while an LLM is still generating it, when playback needs to start as soon as possible: you can send the text in several pieces, audio is returned while it is being synthesized, and the first audio chunk usually arrives in about 0.3 seconds. The model, voices, speech tags and pricing are the same as grok-tts.
Connection
wss://api.88api.ai/v1/tts?model=grok-tts&voice=eve&codec=mp3&language=en
Authorization: Bearer $API_KEYAll parameters go in the query string of the connection URL:
| Parameter | Required | Default | Description |
|---|---|---|---|
model | Yes | — | grok-tts |
voice | No | eve | See the voice table above |
codec | No | mp3 | mp3, wav, pcm, mulaw (ulaw also accepted), alaw; opus, aac and flac are not supported |
language | No | Auto-detected | Language code, such as zh, en, ja |
sample_rate | No | 24000 | 8000, 16000, 22050, 24000, 44100, 48000 |
bit_rate | No | 128000 | MP3 only: 32000, 64000, 96000, 128000, 192000 |
speed | No | 1.0 | Speed multiplier, range 0.7–1.5 |
text_normalization | No | false | true or false; when true, numbers, abbreviations and symbols are converted to their spoken form before synthesis |
Messages
Once the connection is open, both sides send JSON text messages:
| Direction | Message | Description |
|---|---|---|
| Client sends | {"type": "text.delta", "delta": "..."} | Appends text to read aloud; can be sent several times in a row |
| Client sends | {"type": "text.done"} | This segment of text is complete |
| Server returns | audio.delta | delta is a Base64-encoded audio chunk; concatenate the chunks in the order received to get the complete audio |
| Server returns | audio.done | All audio for this segment has been returned |
| Server returns | error | Synthesis of this segment failed; details are in the message |
Actual response example:
{"type": "audio.delta", "delta": "//PExABLjDncBN4ZECBPfcTHl40IKQ..."}
{"type": "audio.done", "trace_id": "a52a926b-726f-439c-bbeb-5d741dd497ad"}- The connection stays open after
audio.done; you can sendtext.deltaandtext.donefor the next segment without reconnecting. - Billed by the number of text characters in segments that were actually synthesized into audio, at the same price as
grok-tts; segments that fail to synthesize and connections that send no text are not billed. - Only JSON text messages are supported; do not send binary frames.
- Parameters are validated before the connection is established: if
voiceis not in the voice table (including OpenAI voice names), orcodec,sample_rate,speedor another parameter has an invalid value, the handshake returns HTTP400directly and no WebSocket connection is established; the error message describes the valid values.
Python
Requires websockets 14 or later (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=en"
async def main():
async with websockets.connect(
URL, additional_headers={"Authorization": f"Bearer {API_KEY}"}
) as ws:
segments = [
["Welcome to 88API ", "streaming text to speech, ", "which reads text aloud as it is generated."],
["The same connection can go on to synthesize the next segment."],
]
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
Uses the ws library (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=en";
const ws = new WebSocket(url, {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const chunks = [];
ws.on("open", () => {
for (const delta of ["I opened the door, ", "[pause] and there it was. ", "<whisper>It's a secret.</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 speech to text (grok-stt)
cURL
Upload audio as multipart/form-data. Let cURL or your SDK generate the multipart boundary; do not set the Content-Type: multipart/form-data header by hand.
curl --fail-with-body https://api.88api.ai/v1/audio/transcriptions \
-H "Authorization: Bearer $API_KEY" \
-F "model=grok-stt" \
-F "language=en" \
-F "keyterm=88API" \
-F "file=@./meeting.mp3"Response:
{
"text": "Welcome to the 88API speech service. Today is October 17th, 2026."
}Request fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
file | file | Yes | — | Audio or video file: mp3, wav, ogg, opus, flac, aac, m4a, mp4, mkv; browser-recorded webm also works |
model | string | Yes | — | grok-stt |
response_format | string | No | json | json, text, verbose_json; srt and vtt return 400 |
language | string | No | Auto-detected | Language code, such as zh, en, ja, yue (Cantonese); setting it makes recognition more stable |
format | boolean | No | false | When true, spoken numbers, amounts and similar are converted to written form; requires language |
keyterm | string | No | — | Proper nouns to prioritize, such as product names or personal names; repeat the field to send several, one term each. Without keyterm, product names such as 88API may be misrecognized |
filler_words | boolean | No | false | When true, filler words such as "um" and "uh" are kept; they are removed by default |
OpenAI's prompt, temperature and timestamp_granularities have no effect on grok-stt and are ignored. Use keyterm when you need the model to get proper nouns right.
Response formats
response_format | Content-Type | Content |
|---|---|---|
json | application/json | {"text": "..."} |
text | text/plain | Plain text |
verbose_json | application/json | text, language, duration (seconds), and per-word timestamps words (word, start, end) |
verbose_json example:
{
"task": "transcribe",
"language": "en",
"duration": 6.768,
"text": "Welcome to the 88API speech service. Today is October 17th, 2026.",
"words": [
{ "word": "Welcome", "start": 0.16, "end": 0.521 },
{ "word": "to", "start": 0.561, "end": 0.621 }
]
}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="en",
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: "en",
});
console.log(transcription.text);Grok realtime voice conversation (grok-voice)
Talk with the model in real time over a single WebSocket connection: send text or microphone audio, and the model replies directly in speech, together with a transcript. Suited to voice assistants, phone customer service, speaking practice and similar scenarios.
| Model | Description |
|---|---|
grok-voice-latest | Always points to the latest version, currently grok-voice-3.0 |
grok-voice-3.0 | Pinned version |
Connection
wss://api.88api.ai/v1/realtime?model=grok-voice-latest
Authorization: Bearer $API_KEYThe event protocol is the same as xAI Realtime. Once connected, the server first sends session.created and conversation.created; the client then configures the session and starts the conversation.
- By default, audio is sent and received Base64-encoded inside JSON events. You can also switch to binary transport, where raw audio travels directly as WebSocket binary frames; see Binary audio transport.
- A browser WebSocket cannot set the
Authorizationheader, and your API key should not be exposed in front-end code. Open the connection from your own server, then relay the audio to the browser or app. - Audio format: both input and output are PCM16 (16-bit little-endian), 24 kHz, mono.
Session setup
{
"type": "session.update",
"session": {
"voice": "eve",
"instructions": "You are the 88API voice assistant. Keep your answers concise.",
"turn_detection": { "type": "server_vad" }
}
}| Field | Description |
|---|---|
voice | Voice used for replies; the same 28 voices as grok-tts (see the voice table above); case-insensitive; defaults to ara |
instructions | System instructions that set the role, tone, answer length and so on |
turn_detection | {"type": "server_vad"}: the server replies automatically once it detects you have finished speaking; null (default): you commit the audio and request a reply manually |
- If
voiceis not in the voice table (including OpenAI voice names), you receive anerrorevent witherror.paramset tosession.voice. The wholesession.updatedoes not take effect and the connection stays open; correct it and send it again. session.updateddoes not echo the voice. The current voice is shown only insession.createdwhen the connection opens, for example the defaultxai_ara.
Client events
| Event | Description |
|---|---|
session.update | Sets the voice, system instructions and turn detection |
conversation.item.create | Sends a text message (input_text in content) |
response.create | Requests a reply from the model |
input_audio_buffer.append | Appends a chunk of audio; audio is Base64-encoded PCM16 data, about 100 ms per chunk is recommended |
input_audio_buffer.commit | Commits the appended audio as one user message; used when turn_detection is null |
Send text:
{"type": "conversation.item.create", "item": {"type": "message", "role": "user", "content": [{"type": "input_text", "text": "Introduce yourself in one sentence."}]}}
{"type": "response.create"}Send speech: send input_audio_buffer.append continuously. With server_vad enabled, a stretch of silence after you finish speaking triggers an automatic reply; when turn_detection is null, send input_audio_buffer.commit and response.create once the audio has been sent.
Server events
| Event | Description |
|---|---|
session.created, session.updated | Session created; settings applied |
input_audio_buffer.speech_started / speech_stopped | server_vad detected the start or end of speech |
conversation.item.input_audio_transcription.completed | Recognized text of the user's speech, in transcript |
response.output_audio.delta | Reply audio chunk; delta is Base64-encoded PCM16, 24 kHz, mono |
response.output_audio_transcript.delta / .done | Transcript of the reply; transcript in .done is the full text |
response.done | This reply turn is finished |
ping | Heartbeat; can be ignored |
error | Error; details are in error.message and error.code |
Sending this text message with the session settings above actually returns (excerpt):
{"type": "response.output_audio_transcript.delta", "delta": "Hi, I'm 88API, your concise voice assistant."}
{"type": "response.output_audio.delta", "delta": "<Base64 audio>"}
{"type": "response.output_audio_transcript.done", "transcript": "Hi, I'm 88API, your concise voice assistant."}
{"type": "response.output_audio.done"}
{"type": "response.done", "response": {"status": "completed", "output": [{"type": "message", "role": "assistant", "content": [{"type": "audio", "transcript": "Hi, I'm 88API, your concise voice assistant."}]}]}}Billing
- Billed by call duration: counted per second from when the connection opens until it closes, including idle time when no one is speaking, so close the connection as soon as you are done. See the model marketplace in the console for prices.
- Each user text message (
conversation.item.createwithinput_text) incurs a small additional charge; speech input and the model's spoken replies are not billed separately. - If your balance or token quota does not cover 1 minute of call time, you receive
error(withcodeinsufficient_user_quota) right after the connection opens and the connection is closed. If your balance runs out during a call, you receive the sameerrorwithin 30 seconds, and the connection is then closed with close code1008.
Python
Requires websockets 14 or later (pip install websockets). The example below sends a text message and saves the spoken reply as 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": "You are the 88API voice assistant. Keep your answers concise.",
"turn_detection": {"type": "server_vad"},
},
}))
await ws.send(json.dumps({
"type": "conversation.item.create",
"item": {
"type": "message",
"role": "user",
"content": [{"type": "input_text", "text": "Introduce yourself in one sentence."}],
},
}))
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("Transcript:", 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())To send speech, send 24 kHz, 16-bit, mono audio in chunks. With the session above, which enables server_vad, this can replace the two messages that send text:
with wave.open("question.wav", "rb") as f: # 24 kHz, 16-bit, mono
pcm = f.readframes(f.getnframes())
pcm += b"\x00" * 48000 # Append 1 second of silence so server_vad detects the end of speech
for i in range(0, len(pcm), 4800): # 100 ms per chunk
await ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": base64.b64encode(pcm[i:i + 4800]).decode(),
}))For live microphone input, send the captured audio directly; no padding silence is needed.
Node.js
Uses the ws library (npm install ws). This example disables server_vad, requests a reply manually after sending text, and saves the reply as 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 = [];
// Add a WAV header to PCM16 24 kHz mono data
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: "Answer in one sentence.", turn_detection: null },
});
send({
type: "conversation.item.create",
item: {
type: "message",
role: "user",
content: [{ type: "input_text", text: "What is the capital of France?" }],
},
});
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;
}
});Binary audio transport
Set transport to "binary" for both input and output in session.update, and raw PCM audio is sent and received directly as WebSocket binary frames, with no Base64 encoding or decoding:
{
"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" }
}
}
}- Sending: each binary frame is a chunk of raw PCM16, 24 kHz, mono audio, with 100 ms (4800 bytes) per frame recommended; it replaces
input_audio_buffer.append. - Receiving: reply audio comes back as binary frames and there are no more
response.output_audio.deltaevents; concatenate the frames in the order received. - Control events such as
input_audio_buffer.commitandresponse.create, as well as server events such assession.updated, transcripts andresponse.done, are still JSON text frames. - Billing is unchanged.
Python example: send a spoken question and save the spoken reply as 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, mono
pcm = f.readframes(f.getnframes())
for i in range(0, len(pcm), 4800): # 100 ms per frame, sent as raw 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): # Binary frame: reply audio
audio += message
continue
event = json.loads(message) # Text frame: control event
if event["type"] == "response.output_audio_transcript.done":
print("Transcript:", 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 text to speech
Gemini text to speech currently offers only gemini-3.8-flash-tts, called through the Gemini native endpoint. /v1/audio/speech is not supported (it returns 500 "模型没有返回音频" (the model returned no audio) and is not charged). The former gemini-3.1-flash-tts, gemini-3.8-flash-lite-tts, gemini-2.5-flash-tts and gemini-2.5-pro-tts are no longer available; if you need /v1/audio/speech or streaming audio, use Grok text to speech.
cURL
The key is still your 88API API key and can be sent in the x-goog-api-key header.
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": "Welcome to the 88API speech service. <laugh> What a lovely day." }] }],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } }
}
}
}'Response and download
The response is JSON and contains no audio data. Instead, candidates[0].content.parts[0].text holds an audio download link as a Markdown link (the link text is always 「生成音频」, "generated audio"):
{
"candidates": [{
"content": {
"role": "model",
"parts": [{ "text": "[生成音频](https://example.com/contents/xxxxxxxx.wav)" }]
},
"finishReason": "STOP"
}]
}- Take the URL in the parentheses and download it; no API key is needed for the download. The audio is a WAV file (24 kHz, 16-bit, mono).
- The link is kept for only a few hours and cannot be downloaded after it expires, so download and save it as soon as you get the response.
- Billed by input and output tokens; see the model marketplace in the console for prices.
- The streaming endpoint
POST /v1beta/models/gemini-3.8-flash-tts:streamGenerateContent?alt=ssecan be called, but it does not return audio in chunks: once synthesis finishes, it returns the same download link in a single event.
Reading rules
- Verbatim reading: every word in the text is read aloud. Do not put directions such as "Say cheerfully:" in the text, or that sentence will be read aloud too.
- Tone is controlled with angle-bracket tags in the text, and the tags themselves are not read aloud, for example
<laugh>(laugh),<short pause>(short pause),<whispers>(whisper),<sigh>(sigh).
Voices
Set the voice in speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName; there are 30 preset voices. Style descriptions come from the official Google voice list. Every voice can read Chinese and many other languages.
| Voice | Style | Gender |
|---|---|---|
Achernar | Soft | Female |
Achird | Friendly | Male |
Algenib | Gravelly | Male |
Algieba | Smooth | Male |
Alnilam | Firm | Male |
Aoede | Breezy | Female |
Autonoe | Bright | Female |
Callirrhoe | Easy-going | Female |
Charon | Informative | Male |
Despina | Smooth | Female |
Enceladus | Breathy | Male |
Erinome | Clear | Female |
Fenrir | Excitable | Male |
Gacrux | Mature | Female |
Iapetus | Clear | Male |
Kore | Firm | Female |
Laomedeia | Upbeat | Female |
Leda | Youthful | Female |
Orus | Firm | Male |
Puck | Upbeat | Male |
Pulcherrima | Forward | Female |
Rasalgethi | Informative | Male |
Sadachbia | Lively | Male |
Sadaltager | Knowledgeable | Male |
Schedar | Even | Male |
Sulafat | Warm | Female |
Umbriel | Easy-going | Male |
Vindemiatrix | Gentle | Female |
Zephyr | Bright | Female |
Zubenelgenubi | Casual | Male |
If you are unsure, start with Kore (female) and Charon (male). For updates to voices and languages, see the official Google Gemini-TTS documentation.
Two-speaker dialogue
Replace voiceConfig inside speechConfig with multiSpeakerVoiceConfig and assign a voice to each of up to 2 speakers. Write each line of the text only as "Name: line", and do not add a direction such as "TTS the following conversation…" (it would be read aloud):
{
"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" } } }
]
}
}
}
}The result comes back the same way as for a single speaker: a WAV download link.
Gemini speech to text
| Model | Notes |
|---|---|
gemini-3-stt | Recommended for everyday transcription, meetings, subtitles |
gemini-3.5-stt | For more difficult audio; higher unit price |
gemini-3.5-transcribe | Dedicated transcription model; auto-detects 85+ languages, up to about 1 hour of audio per request, fast |
All three models are called the same way; swap in another model name in the examples below. For how gemini-3.5-transcribe differs, see gemini-3.5-transcribe. There are three ways to call them: upload a file to /v1/audio/transcriptions (recommended), pass audio in the chat endpoint, or use the Gemini native endpoint.
Upload a file (recommended)
As with grok-stt, upload the audio as multipart/form-data; do not set the Content-Type: multipart/form-data header by hand.
curl --fail-with-body https://api.88api.ai/v1/audio/transcriptions \
-H "Authorization: Bearer $API_KEY" \
-F "model=gemini-3-stt" \
-F "language=en" \
-F "file=@./meeting.mp3"Response:
{
"text": "Welcome to the 88 API speech service. Today is October 17th, 2026."
}| Field | Type | Required | Default | Description |
|---|---|---|---|---|
file | file | Yes | — | Audio file; common formats such as mp3, wav, m4a, ogg and flac all work, up to 25 MB |
model | string | Yes | — | gemini-3-stt, gemini-3.5-stt or gemini-3.5-transcribe |
response_format | string | No | json | json ({"text": "..."}), text (plain text), verbose_json (also includes task, language, duration); srt and vtt return 400 |
language | string | No | Auto-detected | Language code, such as zh, en, yue (Cantonese) |
prompt | string | No | — | Hints such as the scene, names and terminology, to help recognition; has no effect on gemini-3.5-transcribe |
verbose_json does not include per-word timestamps (words) or segments (segments); if you need per-word timestamps, use grok-stt or the native endpoint of gemini-3.5-transcribe. Files over 25 MB return 400; compress them (for example to 16 kHz mono MP3) or split them into segments before transcribing.
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="en",
)
print(result.text)Chat endpoint (audio input)
Put the audio into a chat message as Base64, and the model outputs a transcript according to your text instruction. You can describe the scene, names and terminology in the instruction to help the model recognize them accurately.
cURL
First convert the audio to Base64, then put it in 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": "Transcribe this audio. Output only the transcript." },
{ "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.jsonThe transcript is in choices[0].message.content. Set format to the audio format, such as mp3 or 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": "Transcribe this audio. Output only the transcript."},
{"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: "Transcribe this audio. Output only the transcript." },
{ type: "input_audio", input_audio: { data: audio, format: "mp3" } },
],
}],
});
console.log(completion.choices[0].message.content);Gemini native endpoint
{
"contents": [{
"role": "user",
"parts": [
{ "text": "Transcribe this audio. Output only the transcript." },
{ "inlineData": { "mimeType": "audio/wav", "data": "<Base64 audio>" } }
]
}]
}Send it to POST https://api.88api.ai/v1beta/models/gemini-3-stt:generateContent with the header x-goog-api-key: $API_KEY.
The chat and native endpoints send the audio as Base64 in the request body, which suits shorter recordings; for larger files, use file upload transcription. The retired gemini-2.5-stt and gemini-3.6-stt should be replaced with gemini-3-stt, gemini-3.5-stt or grok-stt.
gemini-3.5-transcribe
A dedicated transcription model: it needs only audio and neither needs nor accepts text instructions.
/v1/audio/transcriptions: setlanguageto a BCP-47 language code such aszh,enoryue; invalid codes return400.prompthas no effect. The model does not return the detected language; thelanguageinverbose_jsonis the value you sent, or an empty string if you sent none.- Chat endpoint: text in the messages is ignored and not billed, so send only
input_audio. Including asystemmessage orreasoning_effortreturns400. - Native endpoint: use
generationConfig.audioTranscriptionConfigto set the language, custom vocabulary, speaker diarization and per-word timestamps. - Realtime streaming transcription is not provided.
Native endpoint example:
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 audio>" } }]
}],
"generationConfig": {
"audioTranscriptionConfig": { "diarization": true, "wordTimestamp": true }
}
}'audioTranscriptionConfig field | Type | Description |
|---|---|---|
languageCodes | string[] | Audio language as BCP-47 codes, such as ["zh"]; auto-detected if omitted |
customVocabulary | string[] | Proper nouns to prioritize in recognition, such as ["88API"]; these words count toward input usage |
diarization | boolean | Distinguish speakers; each result segment includes speakerLabel (experimental) |
wordTimestamp | boolean | Return per-word timestamps words (experimental) |
mode | string | SMART: smart transcription mode with longer processing time; cannot be combined with diarization or wordTimestamp, otherwise returns 400 |
Actual response for a two-speaker conversation (candidates[0].content.parts, excerpt):
[
{
"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" }
]
}
}
]Without speaker diarization, the full transcript is in parts[0].text. Speaker diarization and per-word timestamps are experimental: with mixed Chinese and English audio, segments in the non-dominant language may be dropped. If you need the complete text, turn both options off.
Common errors
| Status | Typical cause | Action |
|---|---|---|
400 | Missing input / file, a voice name not in the voice table (including OpenAI voice names), unsupported format or sample rate, speed out of range, text too long, upload over 25 MB | Fix the request according to the error message and the fields on this page |
400 | A speech model was called through the Chat, Responses or Messages endpoint | Use the matching endpoint from this page |
400 | Text blocked by the safety policy (PROHIBITED_CONTENT) | Change the text and retry; resending the same content will not help |
401 | Missing or invalid API key | Check the Bearer token; never expose the key in browser front-end code |
429 | Rate, quota or capacity limit | Retry with exponential backoff and check your account balance |
500 / 502 / 503 | Temporary server or upstream failure | Retry a limited number of times; if it still fails, contact support with the request ID |
The request id in error responses is what support uses to investigate, so keep it in your logs; do not log API keys, private audio or sensitive transcripts.