Developer Portal

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

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

curl -X POST https://api.aisupervisor.kz/api/v1/stt/upload \
  -H "X-API-Key: $AIBS_API_KEY" \
  -F "file=@dialog.mp3" \
  -F "language=kz"

# {"recording_id": "b68257a2-5e8c-445a-ba30-b41db6c5d6e5",
#  "status": "completed",
#  "transcript": {"text": "Сәлеметсіз бе, менің атым Әсел…"}}

import requests, time

BASE = "https://api.aisupervisor.kz"
H = {"X-API-Key": API_KEY}

with open("dialog.mp3", "rb") as f:
    r = requests.post(f"{BASE}/api/v1/stt/upload",
                      headers=H,
                      files={"file": f},
                      data={"language": "kz"},
                      timeout=40)
data = r.json()

if data["status"] == "completed":
    print(data["transcript"]["text"])
else:
    # Not ready in time — poll by recording_id.
    rid = data["recording_id"]
    for _ in range(12):
        time.sleep(5)
        t = requests.get(f"{BASE}/api/v1/recordings/transcript",
                         headers=H, params={"recording_id": rid}, timeout=15)
        if t.status_code == 200:
            print(t.json()["transcript"]["text"])
            break

import { readFileSync } from "node:fs"

const BASE = "https://api.aisupervisor.kz"
const H = { "X-API-Key": process.env.AIBS_API_KEY }

const form = new FormData()
form.append("file", new Blob([readFileSync("dialog.mp3")]), "dialog.mp3")
form.append("language", "kz")

const res = await fetch(`${BASE}/api/v1/stt/upload`, {
  method: "POST",
  headers: H,
  body: form,
})
const data = await res.json()

if (data.status === "completed") {
  console.log(data.transcript.text)
} else {
  // Not ready in time — poll by recording_id.
  const url = `${BASE}/api/v1/recordings/transcript?recording_id=${data.recording_id}`
  for (let i = 0; i < 12; i++) {
    await new Promise((r) => setTimeout(r, 5000))
    const t = await fetch(url, { headers: H })
    if (t.ok) {
      console.log((await t.json()).transcript.text)
      break
    }
  }
}

Базовый адрес — https://api.aisupervisor.kz. Все запросы по HTTPS, загрузка аудио — multipart/form-data, ответы в JSON с кодировкой UTF-8 (транскрипт может содержать кириллицу).

Запрос к /stt/upload может выполняться до 25–30 секунд. Установите таймаут HTTP-клиента не меньше 30 секунд — значения по умолчанию у большинства библиотек ниже, и это самая частая причина «сервис не отвечает» на первой интеграции.

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

Поддерживаются два способа. Для серверной интеграции рекомендуется API-ключ: он передаётся в заголовке X-API-Key: <ваш_ключ> и привязан к вашей организации (tenant).

Второй способ — JWT от имени пользователя: POST /api/v1/auth/login с email и password возвращает access_token, refresh_token и expires_in (по умолчанию 3600 секунд). Токен передаётся как Authorization: Bearer <access_token>.

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

Эндпоинты

Загрузка идёт одним запросом: POST /api/v1/stt/upload принимает поля file и language (kz или ru, поле обязательное) и обычно отвечает готовым текстом за несколько секунд. Если результат не успел подготовиться, в ответе придёт status: "queued" и recording_id, по которому транскрипт забирается отдельным запросом.

Поддерживаемые форматы аудио

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

Ответ всегда содержит recording_id и status. Текст приходит в transcript.text — но только при status: "completed", поэтому читать это поле без проверки статуса нельзя.

{
  "recording_id": "b68257a2-5e8c-445a-ba30-b41db6c5d6e5",
  "status": "completed",
  "transcript": { "text": "Сәлеметсіз бе, менің атым Әсел, қош келдіңіз..." }
}

Если результат ещё не готов:

{
  "recording_id": "b68257a2-5e8c-445a-ba30-b41db6c5d6e5",
  "status": "queued",
  "message": "Transcription not ready yet. Retry GET /api/v1/recordings/transcript?recording_id=..."
}

Рекомендуемый сценарий

1. Получите API-ключ (или войдите через /auth/login и используйте JWT).
2. Отправьте аудио на POST /api/v1/stt/upload, указав language.
3. При status: "completed" заберите текст из transcript.text.
4. При queued сохраните recording_id и через несколько секунд запросите GET /api/v1/recordings/transcript, повторяя с интервалом 5–10 секунд.
5. При failed повторите загрузку; при повторных сбоях — в поддержку.

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

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

Коды ошибок

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

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

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

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