OpenAI-совместимый API (аудио)¶
Методы распознавания и синтеза речи в формате OpenAI Audio API. Вы можете использовать официальный клиент openai, указав в нём base_url вашего экземпляра сервиса.
Настройка клиента¶
Задайте в клиенте два параметра:
- Base URL: —
- API-ключ: действующий ключ платформы (как и для остальных методов, см. Аутентификация).
Клиент openai передаёт ключ по схеме Authorization: Bearer <ключ> — эта схема поддерживается, поэтому достаточно указать ключ в api_key:
Распознавание речи (STT)¶
Метод соответствует client.audio.transcriptions.create(). Запрос отправляется в формате multipart/form-data.
Модели¶
GigaAM v3 RNNT выбирается через model="GigaAM-v3-RNNT" с language="ru".
Здесь доступно файловое распознавание с stream=false. Для потока с
уточнением финалов RNNT используйте WebSocket или gRPC.
Значение модели по умолчанию сохраняется.
| Модель | Описание | Стриминг |
|---|---|---|
SpeechExpert-STT-RU |
Файловое распознавание русской речи, в том числе телефонных записей | используйте T-One |
SpeechExpert-STT-Heavy |
Усиленное распознавание сложных и шумных записей, только русский язык; текст без диаризации и точных таймкодов | нет |
SpeechExpert-STT-KK-Large |
Улучшенное файловое распознавание казахской речи (kk), текст без диаризации и точных таймкодов |
нет |
SpeechExpert-STT-TG-Large |
Улучшенное файловое распознавание таджикской речи (tg), текст без диаризации и точных таймкодов |
нет |
SpeechExpert-STT-KY-Large |
Улучшенное файловое распознавание кыргызской речи (ky), текст без диаризации и точных таймкодов |
нет |
SpeechExpert-STT-HY-Large |
Улучшенное файловое распознавание армянской речи (hy), нормализованный текст без диаризации и точных таймкодов |
нет |
SpeechExpert-STT-UZ-Large |
Улучшенное локальное файловое распознавание узбекской речи (uz); пофразовые таймкоды при доступной разметке, без пословных; без диаризации |
нет |
SpeechExpert-STT-UZ |
Файловое распознавание узбекской речи | используйте SpeechExpert-STT-UZ-stream |
Whisper-Kotib-UZ |
Локальное файловое распознавание узбекской речи (uz), без диаризации и точных таймкодов |
нет |
Whisper-Callcenter-UZ |
Локальное файловое распознавание узбекской речи (uz), включая телефонные записи; без диаризации и точных таймкодов |
нет |
Uzinfocom-FastConformer-UZ |
Локальное файловое распознавание узбекской речи (uz), без диаризации и точных таймкодов |
нет |
SpeechExpert-STT-EN |
Файловое распознавание английской речи | нет |
Parakeet-EN |
Английская речь | да (stream=true) |
T-One |
Потоковая выдача результата для русской речи | да (stream=true) |
SpeechExpert-STT-UZ-stream |
Потоковая выдача результата для узбекской речи | да (stream=true) |
SpeechExpert-STT-KK-stream |
Потоковая выдача результата для казахской речи | да (stream=true) |
SpeechExpert-STT-TG-stream |
Потоковая выдача результата для таджикской речи | да (stream=true) |
Whisper-Large-v3-Turbo |
Whisper Large v3 Turbo (офлайн) | нет |
GigaAM-v3-RNNT |
Русская речь; текст без пословных таймкодов | нет (используйте WebSocket или gRPC) |
Mhery-RNNT |
Локальное распознавание армянской речи (hy); без точных пословных таймкодов |
да (stream=true) |
Yandex-SpeechKit |
Yandex STT: распознавание русских файлов в mono с пословными таймкодами, без диаризации | нет |
GigaAM-Multilingual-Large-CTC |
Файловое распознавание для ru, kk, ky, uz |
нет |
GigaAM-UZ-0.6B |
Узбекская модель с нативной пунктуацией; без диаризации и точных пословных таймкодов | нет |
ElevenLabs-Scribe-v2 |
Внешняя модель ElevenLabs для 75 курируемых языков, включая ru, en, kk, ky, uz, tg |
нет |
ElevenLabs-Scribe-v3 |
Scribe v3 через ElevenLabs для 75 курируемых языков, включая ru, en, kk, ky, uz, tg, hy |
нет |
ElevenLabs-Scribe-v2-Medical |
Scribe v2 для медицинской и клинической речи; тот же набор 75 языков | нет |
ElevenLabs-Scribe-v2-Realtime |
Потоковое распознавание через ElevenLabs для 75 языков сервиса; без дополнительного файлового уточнения | только stream=true |
gemini-3.5-transcribe |
Внешняя мультиязычная Gemini 3.5 Transcribe через Google API; публичный профиль включает ru, en, kk, ky, uz, tg |
нет |
gpt-transcribe |
GPT Transcribe через OpenAI для ru, en, kk, ky, uz, tg, hy; mono, без диаризации и точных таймкодов |
нет |
Каноническое имя русского потока в запросах и ответах — T-One;
прежнее имя остаётся входным алиасом для совместимости.
Для GPT Transcribe передайте model="gpt-transcribe" и stream=false.
OpenAI определяет язык по аудио; поле language не отправляется провайдеру
как ограничение. Размер подготовленного mono WAV — не более 25 МБ.
Списание — стоимость OpenAI ×2, с переводом в кредиты по курсу сервера и
округлением длительности вверх до целой секунды. Возможности, внешняя
обработка и актуальная ставка описаны в STT v1.
Для SpeechExpert Heavy передайте model="SpeechExpert-STT-Heavy",
language="ru" и stream=false. Запись обрабатывается целиком; несколько
аудиоканалов сводятся в mono. Ответ содержит только итоговый текст.
Для улучшенного узбекского распознавания передайте
model="SpeechExpert-STT-UZ-Large", language="uz" и stream=false.
При распознавании этой моделью аудио и текст обрабатываются в контуре
Speech Expert и не передаются внешним ASR- и LLM-провайдерам. Ответ содержит
готовый текст, при доступной разметке — пофразовые таймкоды, без пословных;
диаризация недоступна, каналы сводятся в mono.
Тариф — 250 кредитов в минуту с минимумом 15 секунд на запрос.
Для пофразовой разметки выберите response_format="verbose_json": в segments[]
возвращаются start и end в секундах и текст фразы; поля words нет.
timing_status="aligned" означает полную временную разметку. При недоступном
выравнивании возвращается полный текст, пустой список сегментов и
timing_status="unavailable"; пустому транскрипту соответствует empty.
Форматы srt и vtt возвращают субтитры с теми же пофразовыми границами.
Если текст непустой, а полная разметка недоступна, запрос SRT/VTT завершается
ошибкой 400; в таком случае используйте json, text или verbose_json.
В форматах json и text по-прежнему возвращается только текст.
with open("uzbek.wav", "rb") as audio:
result = client.audio.transcriptions.create(
file=audio,
model="SpeechExpert-STT-UZ-Large",
language="uz",
response_format="verbose_json",
stream=False,
)
Для отдельных узбекских файловых моделей используйте Whisper-Kotib-UZ,
Whisper-Callcenter-UZ или Uzinfocom-FastConformer-UZ с language="uz" и
stream=false. Эти модели выполняют распознавание локально и возвращают текст
без диаризации и точных таймкодов. Языки, ограничения и тарифы приведены в
STT v1. Перевод и другие отдельно выбранные функции
обработки текста имеют собственные условия передачи данных.
Для улучшенного казахского распознавания передайте model="SpeechExpert-STT-KK-Large",
language="kk" и stream=false. Ответ содержит готовый текст без диаризации
и точных таймкодов; каналы сводятся в mono. Аудио обрабатывается с привлечением
внешнего сервиса. Условия приватного режима и согласия, тариф 250 кредитов
в минуту и минимум 15 секунд на запрос приведены в STT v1.
with open("kazakh.wav", "rb") as audio:
result = client.audio.transcriptions.create(
file=audio,
model="SpeechExpert-STT-KK-Large",
language="kk",
response_format="text",
stream=False,
)
Для таджикского передайте model="SpeechExpert-STT-TG-Large",
language="tg" и stream=false. Ответ содержит итоговый текст без точных
таймкодов; диаризация и раздельные каналы не поддерживаются. Алиас
SpeechExpert-STT-TJ-Large также принимается. Модель использует внешний
сервис обработки аудио; тариф — 250 кредитов в минуту с минимумом 15 секунд
на запрос, как описано в STT v1.
with open("tajik.wav", "rb") as audio:
result = client.audio.transcriptions.create(
file=audio,
model="SpeechExpert-STT-TG-Large",
language="tg",
response_format="text",
)
Для кыргызского передайте model="SpeechExpert-STT-KY-Large",
language="ky" и stream=false. Ответ содержит итоговый текст без диаризации
и точных таймкодов; каналы сводятся в mono. Модель использует внешний сервис
обработки аудио. Тариф — 250 кредитов в минуту с минимумом 15 секунд на запрос,
как описано в STT v1.
with open("kyrgyz.wav", "rb") as audio:
result = client.audio.transcriptions.create(
file=audio,
model="SpeechExpert-STT-KY-Large",
language="ky",
response_format="text",
)
Для улучшенного армянского распознавания передайте model="SpeechExpert-STT-HY-Large",
language="hy" и stream=false. Ответ содержит нормализованный армянский текст
строчными буквами без пунктуации, без диаризации и точных таймкодов; каналы
сводятся в mono. Модель использует внешний сервис обработки аудио. Тариф —
250 кредитов в минуту с минимумом 15 секунд на запрос, как описано в
STT v1.
with open("armenian.wav", "rb") as audio:
result = client.audio.transcriptions.create(
file=audio,
model="SpeechExpert-STT-HY-Large",
language="hy",
response_format="text",
stream=False,
)
Для локального армянского распознавания передайте model="Mhery-RNNT" и language="hy".
При stream=false возвращается итоговый текст файла, при stream=true —
поток SSE с уточнёнными финалами. Исходные написание, числа и пунктуация
результата сохраняются; точные пословные таймкоды не предоставляются.
Qwen3-ASR 1.7B временно отключена в API и кабинете. Актуальные доступные
модели публикуются в GET /api/stt/capabilities.
Для Yandex STT передайте model="Yandex-SpeechKit" и language="ru".
Модель требует stream=false. Диаризация недоступна.
Yandex поддерживает пословные таймкоды; исходные каналы сводятся в mono.
Тарифы приведены в
STT v1: Yandex — 17,073 кредита в минуту
с округлением вверх до 15 секунд.
Для узбекского передайте language="uz", stream=false и
model="GigaAM-UZ-0.6B" либо model="GigaAM-Multilingual-Large-CTC".
GigaAM UZ 0.6B — отдельный вариант с нативной пунктуацией; её ответ содержит
итоговый текст без точных таймкодов и диаризации. Тариф — 8,75 кредита в минуту.
Для ElevenLabs-Scribe-v2, ElevenLabs-Scribe-v3 и ElevenLabs-Scribe-v2-Medical загруженный аудио- или видеоконтейнер передаётся
провайдеру одним запросом. Поддерживается до пяти каналов. Дублирующие каналы
dual-mono перед отправкой сводятся в один, чтобы итоговый text не содержал
повторов.
Для Scribe v3 передайте model="ElevenLabs-Scribe-v3", нужный language
и stream=false; короткий алиас scribe_v3 также принимается.
Тариф — 1750 кредитов за час (около 29,17 кредита, или 1,17 ₽ за минуту),
с округлением длительности до начатой секунды. Нативная диаризация включена
в ставку. Таймкоды и спикеры доступны через STT v1/v3.
Medical использует model_id=scribe_v2_medical у провайдера и тот же тариф,
что Scribe v2. Обе модели предназначены для файлового распознавания;
для живой речи используйте отдельную ElevenLabs-Scribe-v2-Realtime через
WebSocket или gRPC STT v3. Здесь она
доступна с stream=true после загрузки файла; stream=false отклоняется.
Короткий алиас scribe_v2_realtime также принимается.
Языковой набор сервиса описан в разделе Языки и распознавание.
Для gemini-3.5-transcribe аудио передаётся Google API. Модель умеет возвращать
нативные word timestamps и нативную диаризацию через STT v1/v3, однако короткий
OpenAI-совместимый ответ json|text публикует только текст. Поэтому этот маршрут
использует лимит до 60 минут; для режимов STT v1/v3 с word timestamps или
диаризацией действует лимит 30 минут. Диаризация Gemini поддерживает до восьми
спикеров.
Стриминг
Для потоковой выдачи результата передайте stream=true и потоковую модель,
например T-One для ru или SpeechExpert-STT-UZ-stream
для uz. Также доступны SpeechExpert-STT-KK-stream для kk,
SpeechExpert-STT-TG-stream для tg, Parakeet-EN для en
и Mhery-RNNT для hy.
Для 75 языков сервиса можно выбрать ElevenLabs-Scribe-v2-Realtime.
Файл сначала загружается целиком; живой аудиовход доступен через
WebSocket и gRPC.
Параметры запроса¶
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
file |
file | да | — | Аудио- или видеофайл с аудиодорожкой (WAV PCM/IEEE Float, MP3, M4A, MP4, MOV, WebM, MKV и др.) |
model |
string | нет | SpeechExpert-STT-RU |
Идентификатор из таблицы моделей; для потокового ответа выберите совместимую потоковую модель |
language |
string | нет | ru |
Короткий код языка, например ru, en, kk, ky, uz, tg или hy; файловые модели Scribe v2, Scribe v3 и Scribe v2 Medical принимают 75 языков курируемого набора. Совместимость зависит от модели |
response_format |
string | нет | json |
json или text при stream=false; для SpeechExpert-STT-UZ-Large также verbose_json, srt, vtt с пофразовой разметкой |
stream |
boolean | нет | false |
Потоковая выдача результата в формате SSE |
prompt |
string | нет | — | Принимается для совместимости с OpenAI, но сейчас не влияет на распознавание |
temperature |
number | нет | — | Принимается для совместимости с OpenAI, но сейчас игнорируется |
Для GigaAM-Multilingual-Large-CTC поле language обязательно должно
разрешаться в один из кодов публичного профиля ru, kk, ky;
остальные значения отклоняются с HTTP 400 до чтения файла. Для других моделей
действуют их собственные языковые ограничения.
Для kk и ky рекомендуется проверить качество GigaAM на своих записях,
акцентах и словаре. Таджикский tg не поддерживается этой моделью. Он, как и
ru, en, kk, ky, uz, доступен через
gemini-3.5-transcribe и
обе модели ElevenLabs Scribe v2.
OpenAI-совместимый метод использует короткие коды, в отличие от STT v1/v3:
| OpenAI Audio | STT v1/v3 | Язык |
|---|---|---|
ru |
ru-RU |
русский |
en |
en-US |
английский |
kk |
kk-KZ |
казахский |
ky |
ky-KG |
кыргызский |
uz |
uz-UZ |
узбекский |
tg |
tg-TJ |
таджикский |
Код языка не выбирает модель автоматически. Для казахского и кыргызского файла
с локальной моделью передавайте language и model=GigaAM-Multilingual-Large-CTC.
Для узбекского файла используйте language=uz и model=SpeechExpert-STT-UZ.
Для таджикского выбирайте
model=gemini-3.5-transcribe, model=ElevenLabs-Scribe-v2,
model=ElevenLabs-Scribe-v3 или model=ElevenLabs-Scribe-v2-Medical; все четыре внешние модели совместимы
со всеми кодами таблицы.
OpenAI-совместимый контракт с response_format=json|text возвращает только
текст и не публикует таймкоды. Для результата с временной разметкой используйте
STT v1 или STT v3.
Поле multipart file обычно содержит бинарный файл. Для совместимости можно
передать в нём и чистую Base64-строку поддерживаемого аудио/видеоконтейнера:
сервис распознает сигнатуру после декодирования. Data URL с префиксом
data:...;base64, не поддерживается.
Ответ¶
Без стриминга (stream=false или параметр не указан).
При response_format=json:
При response_format=text тело ответа — обычный текст (text/plain).
Потоковый ответ (SSE)¶
При stream=true и потоковой модели потоково выдаётся только ответ:
файл сначала загружается целиком. Для живого входящего аудио используйте
WebSocket или gRPC.
Для ElevenLabs-Scribe-v2-Realtime файл декодируется в mono PCM16 и передаётся
ElevenLabs со скоростью, близкой к длительности аудио. Окончательные фразы
выдаёт Realtime; Scribe v2 и Medical дополнительно не вызываются. Таймкоды
провайдера появляются вместе с окончательными фрагментами; при их недоступности
выдаются оценённые границы фразы без words. Завершение после последнего
аудиофрагмента может занять до 15 секунд при стандартной настройке.
Текст этой модели возвращается без восстановления пунктуации и нормализации
сервиса, сохраняя соответствие пословным таймкодам.
На сервере требуется ELEVENLABS_API_KEY, webhook не нужен; аудио передаётся
внешнему сервису. Подробнее — Scribe Realtime.
Ответ — поток Server-Sent Events (SSE). События:
transcript.text.delta— очередной фрагмент текста;transcript.text.done— завершение с полным текстом после восстановления пунктуации.
Кадры содержат только строку data:. Значения transcript.text.delta и
transcript.text.done находятся в JSON-поле type, а не в отдельном поле SSE
event:. После финального объекта поток завершается обычным EOF; маркер
data: [DONE] не отправляется.
Помимо OpenAI-совместимых полей type, delta и text, Speech Expert добавляет
тайминги, когда выбранная модель их вернула:
| Поле | Тип | Описание |
|---|---|---|
start_ms |
integer | Начало текущей гипотезы или финального диапазона на шкале исходного аудио |
end_ms |
integer | Конец диапазона |
timing_source |
string | Источник таймингов, например native-asr |
words |
object[] | Слова с полями text, start_ms, end_ms |
Пример промежуточного события:
data: {"type":"transcript.text.delta","delta":"добрый день","start_ms":340,"end_ms":1080,"timing_source":"native-asr","words":[{"text":"добрый","start_ms":340,"end_ms":720},{"text":"день","start_ms":760,"end_ms":1080}]}
Финальное событие сохраняет последний диапазон и полный список доступных слов:
data: {"type":"transcript.text.done","text":"Добрый день.","start_ms":340,"end_ms":1080,"timing_source":"native-asr","words":[{"text":"добрый","start_ms":340,"end_ms":720},{"text":"день","start_ms":760,"end_ms":1080}]}
Поля таймингов являются расширением Speech Expert и могут отсутствовать у модели,
который не возвращает временные границы. Клиентам следует воспринимать их как
необязательные. Если финальный текст отличается от предварительного, поле
words у события done
может отсутствовать. Клиенту, которому важны промежуточные тайминги, следует
сохранять words из delta, а не рассчитывать только на финальный объект.
Если распознавание аварийно завершилось уже после отправки SSE-заголовков,
сервер закрывает поток финальным transcript.text.done с накопленным текстом;
отдельного error-события сейчас нет, а HTTP status остаётся 200. Критичным
клиентам следует считать такой поток best-effort и отдельно контролировать
полноту входной длительности.
Примеры использования¶
with open("audio.wav", "rb") as f:
stream = client.audio.transcriptions.create(
model="T-One",
file=f,
language="ru",
stream=True,
)
for event in stream:
if hasattr(event, "delta") and event.delta:
print(event.delta, end="", flush=True)
if hasattr(event, "text") and event.type == "transcript.text.done":
print("\n[Done]", event.text)
Синтез речи (TTS)¶
Метод соответствует client.audio.speech.create(). Тело запроса — application/json.
Параметры запроса¶
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|---|---|---|---|---|
model |
string | нет | tts-1 |
Модель (игнорируется, оставлена для совместимости) |
input |
string | да | — | Текст для синтеза (до 4096 символов) |
voice |
string | нет | первый доступный | Имя встроенного голоса |
response_format |
string | нет | mp3 |
Формат аудио: mp3, opus, aac, flac, wav, pcm |
speed |
number | нет | 1.0 |
Скорость от 0.25 до 4.0 |
Только встроенные голоса
OpenAI-совместимый метод использует только встроенные голоса.
GET /api/tts/v1/voices также возвращает пользовательские
user-voice-*, но этот endpoint их не поддерживает. Для собственного голоса
вызывайте POST /api/tts/v1. Если voice не найден среди
встроенных, сервер без ошибки выбирает первый доступный голос.
Ответ¶
В ответе сервис возвращает бинарный аудиофайл. Тип содержимого зависит от response_format:
| response_format | Content-Type |
|---|---|
mp3 |
audio/mpeg |
opus |
audio/ogg |
wav |
audio/wav |
flac |
audio/flac |
aac |
audio/aac |
pcm |
audio/basic |
Примеры использования¶
from openai import OpenAI
client = OpenAI(base_url="https://api.speech.example.com/api/v1", api_key="<ваш-ключ>")
response = client.audio.speech.create(
model="tts-1",
input="Привет, это синтез речи через OpenAI-совместимый API.",
voice="elena-speech-expert-tts",
response_format="mp3",
speed=1.0,
)
with open("speech.mp3", "wb") as f:
f.write(response.read())
Ошибки¶
| Код | Когда возникает |
|---|---|
400 |
Пустой файл (STT), неизвестная модель, неподдерживаемый стриминг, ошибка декодирования/конвертации или отсутствие доступных голосов (TTS) |
401 |
Не аутентифицирован (отсутствует или неверный API-ключ) |
402 |
Недостаточно кредитов |
413 |
Multipart-файл превышает серверный лимит загрузки |
422 |
Некорректная форма или тело запроса, например неизвестен response_format |
500 |
Внутренняя ошибка синтеза или распознавания |
503 |
Сервис распознавания недоступен |
Неизвестный голос (TTS)
Если переданный voice не найден, ошибка не возвращается — берётся первый доступный голос. Код 400 возникает только если доступных голосов нет.
Формат ошибки — JSON с полем detail: