> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Realtime API

> Создайте краткоживущую браузерную сессию Realtime API и получите клиентский секрет для SDK BeatAPI Realtime.

`POST https://api.beatapi.io/v1/realtime/sessions`

Создайте краткоживущую браузерную сессию Realtime API и получите клиентский секрет для SDK BeatAPI Realtime.

## Авторизация

`Authorization`   `string`   **обязательный**

Передавайте API-ключ BeatAPI как токен Bearer. Создать ключ можно в [панели управления](https://beatapi.io/dashboard).

```
Authorization: Bearer <BEATAPI_API_KEY>
```

Храните постоянные API-ключи на доверенных серверах. Для тела запроса обязателен `Content-Type: application/json`. Если метод принимает `Idempotency-Key`, этот заголовок необязателен, но рекомендуется для безопасных повторных попыток с точно таким же телом.

## Тело запроса

`max_duration_seconds`   `enum<integer>`   **обязательный**

Обязательная максимальная длительность сессии в реальном времени в секундах. Резервируется сумма USD для выбранного тарифа на 15, 60 или 300 секунд.

**Допустимые значения:** `15`, `60`, `300`

---

`allowed_origins`   `string[]`   **обязательный**

Точные значения origin браузерных запросов, которым разрешено использовать краткоживущий секрет сессии.

**Количество:** 1 – 10 элементов

---

`metadata`   `object`   **необязательный**

Необязательные строковые метаданные, заданные сервером для сопоставления с вашими записями. До 20 ключей; длина ключа до 64 символов, значения — до 256 символов.

## Ответ

Успешный запрос возвращает HTTP `201`.

```json
{
  "data": {
    "id": "rts_8K2qA",
    "object": "realtime.session",
    "status": "ready",
    "client_secret": "brt_live_example_short_lived_secret",
    "expires_at": "2026-08-12T10:01:00.000Z",
    "max_duration_seconds": 60,
    "allowed_origins": [
      "https://app.example.com"
    ],
    "credits": {
      "reserved": 1.2,
      "settled": 0,
      "refunded": 0
    },
    "request_id": "req_abc123",
    "created_at": "2026-08-12T10:00:00.000Z",
    "connected_at": null,
    "closed_at": null
  }
}
```

## Подключение в браузере

Установите браузерный SDK:

```bash
npm install @beatapi/realtime
```

```ts
import { createRealtimeClient } from '@beatapi/realtime';

const camera = await navigator.mediaDevices.getUserMedia({ video: true });
const output = document.querySelector<HTMLVideoElement>('#output')!;
const client = createRealtimeClient({ clientSecret: session.client_secret });
const connection = await client.connect({
  input: camera,
  output,
  initial: { prompt: 'Preserve motion while applying the requested style.' },
});
```

Передавайте только краткоживущий `client_secret` на точный origin из `allowed_origins`. Стоимость выбранной длительности резервируется при создании сессии и списывается только после того, как первый удалённый выходной кадр вызовет принятый BeatAPI сигнал биллинга.

* `GET /v1/realtime/sessions/{session_id}` возвращает сведения о сессии Realtime.
* `DELETE /v1/realtime/sessions/{session_id}` закрывает сессию Realtime.

После окончания работы разорвите браузерное соединение, остановите локальные медиадорожки и закройте серверную сессию.

## Следующий шаг

Передайте полученный `client_secret` в `@beatapi/realtime`. Постоянный API-ключ храните на доверенном сервере. После окончания работы в браузере закройте сессию.

## Ошибки

| Статус | Значение                                                                                                                                                                                                                                                                                                                |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Некорректный JSON либо недопустимое поле, значение или сочетание параметров (`bad_request`; сообщение указывает поле), либо входные данные отклонены модерацией (`content_policy_violation`). Повтор без изменений не поможет.                                                                                          |
| `401`  | Ключ не передан (`missing_api_key`), неверен, просрочен, отключён или исчерпал лимит (`invalid_api_key`; точная причина указана в сообщении). Передавайте `Authorization: Bearer <key>`; ключ работает с префиксом `sk-` и без него. Повторять без исправления не следует.                                              |
| `402`  | Недостаточно средств (`insufficient_credits`): баланс равен нулю или меньше стоимости запроса. Пополните баланс, затем отправьте запрос снова. До пополнения повтор не поможет.                                                                                                                                         |
| `409`  | В течение 24 часов `Idempotency-Key` уже использован с другим телом или путём запроса либо первый запрос с этим ключом ещё выполняется (`idempotency_conflict`). Повтор без изменений не поможет.                                                                                                                       |
| `429`  | Слишком много запросов (`rate_limit_exceeded`, в том числе лимит бесплатной модели). Повторите через число секунд из `Retry-After` (также указано в `error.retry_after_seconds`).                                                                                                                                       |
| `503`  | Видео в реальном времени не включено на данном сервере (`realtime_disabled`, повтор не поможет; самостоятельно включить нельзя, обратитесь в поддержку) либо временно нет свободных ресурсов (`realtime_capacity_unavailable`, повтор возможен; повторите вскоре с увеличивающейся задержкой, точное время не указано). |