Речевые API 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 | Нативный generateContent Gemini (возвращает ссылку на скачивание аудио) | Токены |
| Распознавание речи | 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 (аудио на входе) или нативный generateContent Gemini | Токены |
- Актуальные цены смотрите на витрине моделей в консоли. Для токена выберите группу
语音模型(так она называется в консоли) или автоматическую группу. - Голосовые модели работают только через конечные точки из таблицы выше. Вызов TTS-моделей или
grok-sttчерез Chat, Responses или Messages вернёт400с подсказкой использовать правильную конечную точку. - Конечная точка
/v1/audio/translations(перевод аудио на английский) не предоставляется. /v1/audio/speechвозвращает всё аудио одним ответом. Потоковая выдача не поддерживается:stream_format: "sse"вернёт400. Чтобы воспроизводить аудио по мере синтеза, используйте потоковый синтез речи Grok.
Базовый адрес и аутентификация:
Base URL: https://api.88api.ai/v1
Authorization: Bearer $API_KEYСинтез речи Grok (grok-tts)
cURL
curl --fail-with-body https://api.88api.ai/v1/audio/speech \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-tts",
"input": "Добро пожаловать в сервис синтеза речи 88API.",
"voice": "eve",
"language": "ru",
"response_format": "mp3"
}' \
--output speech.mp3Успешный ответ — двоичные аудиоданные, а не JSON; записывайте его прямо в файл. В Windows текст не в ASCII, переданный через -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": "ru", "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=ru
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=ru"
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=ru";
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 boundary — не задавайте заголовок 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=ru" \
-F "keyterm=88API" \
-F "file=@./meeting.mp3"Ответ:
{
"text": "Добро пожаловать в сервис синтеза речи 88API. Сегодня 17 октября 2026 года."
}Поля запроса
| Поле | Тип | Обязательно | По умолчанию | Описание |
|---|---|---|---|---|
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 | Нет | — | Имена собственные, которые нужно распознавать в первую очередь, например названия продуктов (вроде 88API) или имена людей; можно передавать несколько раз, по одному слову за раз |
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": "ru",
"duration": 8.04,
"text": "Добро пожаловать в сервис синтеза речи 88API. Сегодня 17 октября 2026 года.",
"words": [
{ "word": "Добро", "start": 0.12, "end": 0.381 },
{ "word": "пожаловать", "start": 0.461, "end": 0.982 }
]
}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="ru",
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: "ru",
});
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-ключ не следует раскрывать во фронтенде. Устанавливайте соединение на своём сервере и уже оттуда передавайте аудио в браузер или приложение. - Формат аудио: и на входе, и на выходе — PCM16 (16-bit, little-endian), 24 kHz, моно.
Настройка сессии
{
"type": "session.update",
"session": {
"voice": "eve",
"instructions": "Ты голосовой ассистент 88API, отвечай кратко.",
"turn_detection": { "type": "server_vad" }
}
}| Поле | Описание |
|---|---|
voice | Голос ответа; доступны те же 28 голосов, что и у grok-tts (см. таблицу голосов выше), регистр не учитывается, по умолчанию 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 | Отправляет текстовое сообщение (input_text в content) |
response.create | Запрашивает ответ модели |
input_audio_buffer.append | Добавляет фрагмент аудио; audio — данные PCM16 в Base64, рекомендуется примерно по 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 — PCM16 24 kHz моно в Base64 |
response.output_audio_transcript.delta / .done | Текстовая расшифровка ответа; transcript в .done — полный текст |
response.done | Ответ в этом ходе диалога завершён |
ping | Сигнал активности (heartbeat), можно игнорировать |
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."}]}]}}Тарификация
- Тарификация по длительности разговора: время считается посекундно от установки соединения до его закрытия, включая паузы, когда никто не говорит, поэтому закрывайте соединение сразу после использования. Цены смотрите на витрине моделей в консоли.
- За каждое текстовое сообщение пользователя (
conversation.item.createсinput_text) дополнительно взимается небольшая плата; голосовой ввод и голосовые ответы модели отдельно не тарифицируются. - Если баланса или лимита токена не хватает на 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 = [];
// Добавляет заголовок WAV к данным PCM16 24 kHz моно
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
Ключом служит тот же API-ключ 88API; его можно передать в заголовке 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, моно).
- Ссылка хранится всего несколько часов, после истечения скачать файл нельзя — скачивайте и сохраняйте его сразу после получения ответа.
- Оплата — по входным и выходным токенам, цены смотрите на витрине моделей в консоли.
- Потоковый интерфейс
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.
Диалог двух дикторов
Замените voiceConfig внутри speechConfig на 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=ru" \
-F "file=@./meeting.mp3"Ответ:
{
"text": "Добро пожаловать в сервис синтеза речи 88API. Сегодня 17 октября 2026 года."
}| Поле | Тип | Обязательно | По умолчанию | Описание |
|---|---|---|---|---|
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 — сожмите его (например, в моно MP3 16 kHz) или разбейте на части перед расшифровкой.
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="ru",
)
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не действует. Модель не возвращает определённый язык:languageвverbose_json— это переданное вами значение, а если вы его не передали — пустая строка.- Конечная точка чата: текст в сообщениях игнорируется и не тарифицируется, достаточно отправить только
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 | Голосовая модель вызвана через Chat, Responses или Messages | Используйте соответствующую конечную точку из этой страницы |
400 | Текст заблокирован политикой безопасности (PROHIBITED_CONTENT) | Измените текст и повторите; повторная отправка того же содержимого не поможет |
401 | API-ключ отсутствует или недействителен | Проверьте Bearer Token и не раскрывайте ключ во фронтенде браузера |
429 | Ограничение скорости, квоты или мощности | Повторяйте с экспоненциальной задержкой и проверьте баланс аккаунта |
500 / 502 / 503 | Временный сбой сервера или вышестоящего сервиса | Повторите ограниченное число раз; если ошибка сохраняется, обратитесь в поддержку и укажите ID запроса |
request id в ответе с ошибкой нужен для диагностики — сохраняйте его в логах; не записывайте API-ключ, приватное аудио и конфиденциальные расшифровки.