Real-time голосовой API

Откройте живую голосовую сессию с агентом проекта по API-ключу: устройство, приложение или SDK подключается напрямую (WebRTC) и ведёт диалог в реальном времени — с тем же агентом, что и в телефонии, со своей базой знаний и встроенными инструментами.

Как это работает

Ваш бэкенд запрашивает сессию: POST /v1/public/realtime/session (нужен ключ со scope write).
В ответ — доступ к комнате LiveKit: url, token, room.
Устройство/клиент подключается к комнате по любому LiveKit-SDK (JS, Swift, Kotlin, Flutter, Unity, Python…) и включает микрофон.
Агент автоматически присоединяется к комнате и начинает разговор.

Запрос сессии

curl -X POST https://api.maia-ai.com/v1/public/realtime/session \
  -H "X-API-Key: maia_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "ваш-uuid-проекта" }'

Ответ:

{
  "url": "wss://lk.maia-ai.com",
  "token": "eyJhbGciOi...",
  "room": "rt-1a2b3c4d-...",
  "expires_in": 3600,
  "minute_price": "6.65"
}

Подключение клиента

url + token передайте в LiveKit-SDK. Пример на JS (livekit-client):

import { Room } from "livekit-client";
 
const room = new Room();
await room.connect(url, token);              // url и token из ответа выше
await room.localParticipant.setMicrophoneEnabled(true);
// агент подключится к комнате сам и начнёт диалог

То же подключение на других платформах — меняется только LiveKit-SDK.

Python

Python SDK:

from livekit import rtc
 
room = rtc.Room()
await room.connect(url, token)               # url и token из ответа выше
# публикуем аудио с микрофона устройства
source = rtc.AudioSource(48000, 1)
track = rtc.LocalAudioTrack.create_audio_track("mic", source)
await room.local_participant.publish_track(track)
# агент подключится к комнате сам и начнёт диалог

Swift (iOS)

client-sdk-swift:

import LiveKit
 
let room = Room()
try await room.connect(url: url, token: token)    // url и token из ответа выше
try await room.localParticipant.setMicrophone(enabled: true)
// агент подключится к комнате сам и начнёт диалог

Kotlin (Android)

client-sdk-android:

val room = LiveKit.create(appContext)
room.connect(url, token)                           // url и token из ответа выше
room.localParticipant.setMicrophoneEnabled(true)
// агент подключится к комнате сам и начнёт диалог

Тарификация

Сессия тарифицируется поминутно с момента подключения по цене минуты связки проекта (minute_price в ответе), как браузерная голосовая сессия. Перед выдачей токена проверяются активная подписка и достаточный баланс — иначе 402.

Токен действует 1 час (expires_in). Сессия завершается, когда клиент отключается, когда агент сам кладёт трубку или по достижению лимита длительности.

Коды ошибок

Ответ на POST /v1/public/realtime/session:

Код	Когда	Что делать
`401`	Неверный, отозванный или отсутствующий API-ключ	Проверьте заголовок `X-API-Key` или `Authorization: Bearer maia_…`
`403`	У ключа нет scope `write`, либо подписка приостановлена	Выпустите ключ с правом `write`; проверьте статус подписки
`402`	Недостаточно средств на балансе для минуты сессии	Пополните баланс
`404`	Проект не найден или не принадлежит владельцу ключа	Проверьте `project_id`
`429`	Превышен лимит запросов (120/мин на ключ)	Снизьте частоту запросов

См. также: Аутентификация · REST API · API Reference

REST API MCP-сервер