Realtime API

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

Create a short-lived Realtime API browser session and receive a client secret for the BeatAPI realtime SDK.

Authorization

Authorization   string   required

Send your BeatAPI API key as a Bearer token. Create one on the Dashboard.

Authorization: Bearer <BEATAPI_API_KEY>

Keep permanent API keys on trusted servers. Content-Type: application/json is required for the request body. Idempotency-Key is optional when the endpoint exposes it and is recommended for safe retries with the exact same body.

Request body

max_duration_seconds   enum<integer>   required

Required maximum live session duration in seconds. The USD amount is reserved for the selected 15, 60, or 300 second tier.

Available options: 15, 60, 300

allowed_origins   string[]   required

Exact browser origins allowed to use the short-lived session secret.

Count: 1 to 10 items

metadata   object   optional

Optional server-defined string metadata for your own correlation. Up to 20 keys; keys are at most 64 characters and values at most 256 characters.

Response

A successful request returns HTTP 201.

1
{
2
  "data": {
3
    "id": "rts_8K2qA",
4
    "object": "realtime.session",
5
    "status": "ready",
6
    "client_secret": "brt_live_example_short_lived_secret",
7
    "expires_at": "2026-08-12T10:01:00.000Z",
8
    "max_duration_seconds": 60,
9
    "allowed_origins": [
10
      "https://app.example.com"
11
    ],
12
    "credits": {
13
      "reserved": 1.2,
14
      "settled": 0,
15
      "refunded": 0
16
    },
17
    "request_id": "req_abc123",
18
    "created_at": "2026-08-12T10:00:00.000Z",
19
    "connected_at": null,
20
    "closed_at": null
21
  }
22
}

Connect in the browser

Install the browser SDK:

$
npm install @beatapi/realtime

1
import { createRealtimeClient } from '@beatapi/realtime';
2
3
const camera = await navigator.mediaDevices.getUserMedia({ video: true });
4
const output = document.querySelector<HTMLVideoElement>('#output')!;
5
const client = createRealtimeClient({ clientSecret: session.client_secret });
6
const connection = await client.connect({
7
  input: camera,
8
  output,
9
  initial: { prompt: 'Preserve motion while applying the requested style.' },
10
});

Pass only the short-lived client_secret to the exact origin listed in allowed_origins. The selected duration is reserved at creation and settles only after the first remote output frame produces an accepted BeatAPI billing heartbeat.

• GET /v1/realtime/sessions/{session_id} inspects a Realtime Session.
• DELETE /v1/realtime/sessions/{session_id} closes a Realtime Session.

Disconnect the browser connection, stop local media tracks, and close the server-side Session when the experience ends.

Next step

Pass the returned client_secret to @beatapi/realtime. Keep the permanent API key on your trusted server, and close the session when the browser experience ends.

Errors