Developer Portal

Документация STT/ASR API: аутентификация, эндпоинты, форматы ответа и лимиты. Тестовый ключ выдаётся в течение часа в рабочее время — без звонка с отделом продаж.

Быстрый старт

Три шага до первого ответа: получите ключ, отправьте файл, заберите транскрипт. Ниже — минимальный работающий запрос.

curl -X POST https://api.aibs.kz/v1/transcribe \
  -H "Authorization: Bearer $AIBS_API_KEY" \
  -F "file=@dialog.wav" \
  -F "language=kk-ru"

import requests

response = requests.post(
    "https://api.aibs.kz/v1/transcribe",
    headers={"Authorization": f"Bearer {API_KEY}"},
    files={"file": open("dialog.wav", "rb")},
    data={"language": "kk-ru"},
)

for segment in response.json()["segments"]:
    print(segment["start_ms"], segment["speaker"], segment["text"])

import { readFileSync } from "node:fs"

const form = new FormData()
form.append("file", new Blob([readFileSync("dialog.wav")]), "dialog.wav")
form.append("language", "kk-ru")

const res = await fetch("https://api.aibs.kz/v1/transcribe", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.AIBS_API_KEY}` },
  body: form,
})

const { segments } = await res.json()
segments.forEach((s) => console.log(s.start_ms, s.speaker, s.text))

Базовый адрес — https://api.aibs.kz. Все запросы по HTTPS, телоmultipart/form-data, ответы в JSON с кодировкой UTF-8.

Аутентификация

Ключ передаётся в заголовке Authorization: Bearer <ключ>. Ключ привязан к организации, а не к пользователю, и может быть отозван из личного кабинета — отзыв действует немедленно.

Ключ — это секрет: он даёт доступ к вашей квоте и вашим записям. Не кладите его в клиентский код мобильного приложения или фронтенда; запрос к API должен уходить с вашего сервера.

Эндпоинты

Метод	Путь	Назначение
`POST`	`/v1/transcribe`	Асинхронная транскрибация готового файла. Возвращает job_id.
`GET`	`/v1/jobs/{id}`	Статус задачи и, по готовности, транскрипт.
`WS`	`/v1/stream`	Потоковое распознавание в реальном времени. Аудио чанками, ответ — частичные и финальные гипотезы.
`GET`	`/v1/usage`	Израсходованные минуты, остаток и дата сброса.

Транскрибация асинхронная: POST /v1/transcribe отвечает сразу и возвращаетjob_id, результат забирается по GET /v1/jobs/{id}. Часовая запись не должна держать HTTP-соединение открытым две минуты.

Формат ответа

Транскрипт возвращается сегментами: смещения в миллисекундах, метка говорящего и оценка уверенности от 0 до 1 на каждый сегмент.

{
  "job_id": "395aa2cf-edb0-493e-83c6-538b30587a24",
  "status": "completed",
  "language": "kk-ru",
  "duration_ms": 41200,
  "full_text": "Сәлеметсіз бе, чем могу помочь?…",
  "segments": [
    {
      "start_ms": 0,
      "end_ms": 2400,
      "speaker": "Speaker 1",
      "text": "Сәлеметсіз бе, чем могу помочь?",
      "confidence": 0.96
    }
  ]
}

Поле confidence отражает уверенность модели в конкретном сегменте — по нему удобно отправлять на ручную проверку только то, что того стоит.

Лимиты и тарификация

Параметр	Тестовый ключ	Коммерческие тарифы
Объём	60 минут аудио или 100 запросов	По тарифу, от пакета минут
Размер файла	до 100 МБ	Согласуется
Длительность файла	до 2 часов	Согласуется
Параллельные задачи	3	Под профиль нагрузки
Скорость обработки	x30	до x60–x80 на выделенных серверах

Тарификация — по минутам обработанного аудио, округление вверх до минуты. Подробности тарифов на странице STT Core Engine.

Коды ошибок

Код	Причина	Повторять?
`401`	Ключ отсутствует, отозван или не тот	нет
`402`	Лимит минут исчерпан. В теле — limit, used, requested	нет
`413`	Файл больше допустимого размера или длиннее лимита	нет
`415`	Формат не распознаётся как аудио	нет
`429`	Превышена частота запросов. В заголовке — Retry-After	да
`5xx`	Сбой на нашей стороне	да, с экспоненциальной паузой

Повторять стоит только 429 и 5xx, с экспоненциальной паузой. Остальные коды при повторе вернут тот же ответ.

Технический FAQ

Какой у вас WER и на чём он измерен?

Менее 10% на локальном сленге и смешанной казахско-русской речи. Измерение проводится на собственном тестовом наборе из реальных оффлайн-диалогов, а не на чистой студийной речи — на подготовленных записях цифра заметно ниже, но она ничего не говорит о работе в зале с фоновым шумом. Методику и разбивку по доменам отдаём по запросу вместе с тестовым ключом: считаем, что заявленную точность разумно проверять на своих данных.

Какая задержка в потоковом режиме?

Частичные гипотезы приходят в пределах нескольких сотен миллисекунд после конца фразы, финальные — после закрытия сегмента. Для пакетной обработки ориентир другой: скорость x30 к длительности аудио на базовой конфигурации и x60–x80 на выделенных серверах. Час записи на базовой обрабатывается примерно за две минуты.

Какие лимиты на подключения и частоту запросов?

На тестовом ключе — 100 запросов или 60 минут аудио, чего достаточно для интеграционного прототипа. На коммерческих тарифах частота и количество параллельных соединений согласуются под ваш профиль нагрузки: для потоков свыше миллиона минут в месяц резервируются выделенные мощности, и лимит становится вопросом ёмкости, а не тарифа.

Как вы работаете со смешанной казахско-русской речью?

Модель обучена на смешанной речи изначально, а не собрана из двух одноязычных с переключателем. Переключение между языками внутри одной реплики — норма для казахстанского говорящего, и именно на нём заметнее всего проседают глобальные движки: они распознают вставку на другом языке как искажённое слово родного. Указывать язык при запросе не нужно.

Что происходит с моими аудиофайлами?

В облачном режиме файл хранится столько, сколько нужно для обработки и выдачи результата, и удаляется по вашему запросу или по истечении срока хранения в тарифе. Записи клиентов не используются для дообучения моделей без отдельного письменного согласия. Если этого недостаточно — существует On-Premise: развертывание внутри вашего периметра, где вопрос хранения решаете только вы.

Можно ли дообучить модель под нашу терминологию?

Да. Fine-tuning под отраслевую лексику — медицинскую, банковскую, техническую — выполняется на ваших данных. Обучение проходит в нашей закрытой корпоративной среде из-за требований к GPU; датасет не покидает её и не смешивается с чужими.

Получить ключ

Опишите стек и задачу — этого достаточно, чтобы выделить мощности и выдать ключ с тестовым лимитом. В рабочее время это занимает около часа.

Тестовый доступ

Ключ за час, без звонка с продажами

Коллекция Postman и публичные примеры на GitHub появятся здесь же — сейчас готовим репозитории.