88API88API
User GuideAI ApplicationsAPI ReferenceHelp & Support
Audio

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

CapabilityModelsEndpointBilled by
Text to speechgrok-ttsPOST /v1/audio/speechInput characters
Streaming text to speechgrok-ttsWebSocket /v1/ttsInput characters
Realtime voice conversationgrok-voice-latest, grok-voice-3.0WebSocket /v1/realtimeCall duration
Text to speechgemini-3.8-flash-ttsGemini native generateContent (returns an audio download link)Tokens
Speech to textgrok-sttPOST /v1/audio/transcriptionsAudio duration
Speech to textgemini-3-stt, gemini-3.5-stt, gemini-3.5-transcribePOST /v1/audio/transcriptions, POST /v1/chat/completions (audio input), or Gemini native generateContentTokens
  • 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-stt through the Chat, Responses or Messages endpoint returns 400 with a hint to use the correct endpoint.
  • The /v1/audio/translations endpoint (translating audio into English) is not provided.
  • /v1/audio/speech returns the complete audio in one response. Streaming is not supported; stream_format: "sse" returns 400. 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_KEY

Grok 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.mp3

A 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

FieldTypeRequiredDefaultDescription
modelstringYes—grok-tts
inputstringYes—Text to read aloud; must not be empty. You can insert the speech tags described below
voicestringNoeveSee the voice table below; case-insensitive. OpenAI voice names such as alloy and nova return 400
response_formatstringNomp3mp3, wav, pcm, mulaw, alaw; opus, aac and flac return 400
languagestringNoAuto-detectedLanguage code, such as zh, en, ja, ko, fr, ru, vi, pt-BR. A fixed language is more stable than auto-detection
speednumberNo1.0Speed multiplier, range 0.7–1.5; values outside it return 400
sample_rateintegerNo240008000, 16000, 22050, 24000, 44100, 48000; other values return 400
bit_rateintegerNo128000MP3 only: 32000, 64000, 96000, 128000, 192000
text_normalizationbooleanNofalseWhen true, numbers, abbreviations and symbols are converted to their spoken form before synthesis
replaceobjectNo—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_formatContent-TypeDescription
mp3audio/mpeg24 kHz, 128 kbps by default; plays directly
wavaudio/wav16-bit mono; suited to post-editing
pcmaudio/pcm16-bit mono raw PCM with no header; parse it by sample rate
mulawaudio/basicG.711 μ-law for telephony; usually paired with sample_rate: 8000
alawaudio/alawG.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.

VoiceStyleUse cases
eveEnergetic and upbeat, British accent (default)General
araWarm and friendlyGeneral
rexConfident and clearGeneral
salSmooth and balancedGeneral
leoAuthoritative and strong, British accentGeneral
carinaSoft, empathetic, soothingWellness, Support
zaganPowerful, dramaticCharacters, Narration
helixBold, dynamic, adrenaline-fueledCommentary, Podcast
orionRich, cinematic, resonantNarration, Audiobooks
lunaGentle, patient, nurturingEducation, Assistant
irisFriendly, upbeat, charmingSales, Support
altairElegant, refinedAdvertising, Narration
zenithSharp, focused, drivenSales, Advertising
perseusStrong, confident, trustworthyAdvertising, Narration
heliosUpbeat, energetic, versatileAssistant, Wellness
luxGrounded, calm, quietly wiseWellness, Narration
keplerInventive, charismaticAdvertising, Podcast
rigelPrecise, professional, Australian accentAssistant, Support
cosmoBright, curious, easy to followEducation, Podcast
celesteCompassionate, reassuringSupport, Assistant
ursaFriendly, warm, steadfastAssistant, Podcast
siriusQuick-witted, playfulCommentary, Characters
lumenWarm, articulate, engagingEducation, Advertising
castorCharismatic, down-to-earth, easygoingSales, Support
nakshWarm, thoughtful, wise, Indian accentAssistant, Support
atlasConfident, commanding, reassuringSales, Assistant
auroraSerene, steadySupport, Assistant
lioraCalm, groundedWellness, 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.

TypeTags
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_KEY

All parameters go in the query string of the connection URL:

ParameterRequiredDefaultDescription
modelYes—grok-tts
voiceNoeveSee the voice table above
codecNomp3mp3, wav, pcm, mulaw (ulaw also accepted), alaw; opus, aac and flac are not supported
languageNoAuto-detectedLanguage code, such as zh, en, ja
sample_rateNo240008000, 16000, 22050, 24000, 44100, 48000
bit_rateNo128000MP3 only: 32000, 64000, 96000, 128000, 192000
speedNo1.0Speed multiplier, range 0.7–1.5
text_normalizationNofalsetrue 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:

DirectionMessageDescription
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 returnsaudio.deltadelta is a Base64-encoded audio chunk; concatenate the chunks in the order received to get the complete audio
Server returnsaudio.doneAll audio for this segment has been returned
Server returnserrorSynthesis 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 send text.delta and text.done for 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 voice is not in the voice table (including OpenAI voice names), or codec, sample_rate, speed or another parameter has an invalid value, the handshake returns HTTP 400 directly 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

FieldTypeRequiredDefaultDescription
filefileYes—Audio or video file: mp3, wav, ogg, opus, flac, aac, m4a, mp4, mkv; browser-recorded webm also works
modelstringYes—grok-stt
response_formatstringNojsonjson, text, verbose_json; srt and vtt return 400
languagestringNoAuto-detectedLanguage code, such as zh, en, ja, yue (Cantonese); setting it makes recognition more stable
formatbooleanNofalseWhen true, spoken numbers, amounts and similar are converted to written form; requires language
keytermstringNo—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_wordsbooleanNofalseWhen 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_formatContent-TypeContent
jsonapplication/json{"text": "..."}
texttext/plainPlain text
verbose_jsonapplication/jsontext, 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.

ModelDescription
grok-voice-latestAlways points to the latest version, currently grok-voice-3.0
grok-voice-3.0Pinned version

Connection

wss://api.88api.ai/v1/realtime?model=grok-voice-latest
Authorization: Bearer $API_KEY

The 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 Authorization header, 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" }
  }
}
FieldDescription
voiceVoice used for replies; the same 28 voices as grok-tts (see the voice table above); case-insensitive; defaults to ara
instructionsSystem 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 voice is not in the voice table (including OpenAI voice names), you receive an error event with error.param set to session.voice. The whole session.update does not take effect and the connection stays open; correct it and send it again.
  • session.updated does not echo the voice. The current voice is shown only in session.created when the connection opens, for example the default xai_ara.

Client events

EventDescription
session.updateSets the voice, system instructions and turn detection
conversation.item.createSends a text message (input_text in content)
response.createRequests a reply from the model
input_audio_buffer.appendAppends a chunk of audio; audio is Base64-encoded PCM16 data, about 100 ms per chunk is recommended
input_audio_buffer.commitCommits 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

EventDescription
session.created, session.updatedSession created; settings applied
input_audio_buffer.speech_started / speech_stoppedserver_vad detected the start or end of speech
conversation.item.input_audio_transcription.completedRecognized text of the user's speech, in transcript
response.output_audio.deltaReply audio chunk; delta is Base64-encoded PCM16, 24 kHz, mono
response.output_audio_transcript.delta / .doneTranscript of the reply; transcript in .done is the full text
response.doneThis reply turn is finished
pingHeartbeat; can be ignored
errorError; 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.create with input_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 (with code insufficient_user_quota) right after the connection opens and the connection is closed. If your balance runs out during a call, you receive the same error within 30 seconds, and the connection is then closed with close code 1008.

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.delta events; concatenate the frames in the order received.
  • Control events such as input_audio_buffer.commit and response.create, as well as server events such as session.updated, transcripts and response.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=sse can 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.

VoiceStyleGender
AchernarSoftFemale
AchirdFriendlyMale
AlgenibGravellyMale
AlgiebaSmoothMale
AlnilamFirmMale
AoedeBreezyFemale
AutonoeBrightFemale
CallirrhoeEasy-goingFemale
CharonInformativeMale
DespinaSmoothFemale
EnceladusBreathyMale
ErinomeClearFemale
FenrirExcitableMale
GacruxMatureFemale
IapetusClearMale
KoreFirmFemale
LaomedeiaUpbeatFemale
LedaYouthfulFemale
OrusFirmMale
PuckUpbeatMale
PulcherrimaForwardFemale
RasalgethiInformativeMale
SadachbiaLivelyMale
SadaltagerKnowledgeableMale
SchedarEvenMale
SulafatWarmFemale
UmbrielEasy-goingMale
VindemiatrixGentleFemale
ZephyrBrightFemale
ZubenelgenubiCasualMale

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

ModelNotes
gemini-3-sttRecommended for everyday transcription, meetings, subtitles
gemini-3.5-sttFor more difficult audio; higher unit price
gemini-3.5-transcribeDedicated 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.

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."
}
FieldTypeRequiredDefaultDescription
filefileYes—Audio file; common formats such as mp3, wav, m4a, ogg and flac all work, up to 25 MB
modelstringYes—gemini-3-stt, gemini-3.5-stt or gemini-3.5-transcribe
response_formatstringNojsonjson ({"text": "..."}), text (plain text), verbose_json (also includes task, language, duration); srt and vtt return 400
languagestringNoAuto-detectedLanguage code, such as zh, en, yue (Cantonese)
promptstringNo—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.json

The 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: set language to a BCP-47 language code such as zh, en or yue; invalid codes return 400. prompt has no effect. The model does not return the detected language; the language in verbose_json is 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 a system message or reasoning_effort returns 400.
  • Native endpoint: use generationConfig.audioTranscriptionConfig to 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 fieldTypeDescription
languageCodesstring[]Audio language as BCP-47 codes, such as ["zh"]; auto-detected if omitted
customVocabularystring[]Proper nouns to prioritize in recognition, such as ["88API"]; these words count toward input usage
diarizationbooleanDistinguish speakers; each result segment includes speakerLabel (experimental)
wordTimestampbooleanReturn per-word timestamps words (experimental)
modestringSMART: 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

StatusTypical causeAction
400Missing 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 MBFix the request according to the error message and the fields on this page
400A speech model was called through the Chat, Responses or Messages endpointUse the matching endpoint from this page
400Text blocked by the safety policy (PROHIBITED_CONTENT)Change the text and retry; resending the same content will not help
401Missing or invalid API keyCheck the Bearer token; never expose the key in browser front-end code
429Rate, quota or capacity limitRetry with exponential backoff and check your account balance
500 / 502 / 503Temporary server or upstream failureRetry 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.