@beatapi/realtime

The official browser SDK for the BeatAPI Realtime Video API. It connects a browser MediaStream to a live AI video generation session and renders the generated WebRTC output into an HTMLVideoElement.

Your permanent BeatAPI API key stays on your server. The browser receives only the short-lived, origin-bound client_secret returned when the server creates a Realtime Session.

Install

npm install @beatapi/realtime

1. Create a session on your server

Call POST /v1/realtime/sessions from trusted server code. Never put an sk_... key in a browser bundle.

const response = await fetch('https://api.beatapi.io/v1/realtime/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BEATAPI_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    max_duration_seconds: 60,
    allowed_origins: ['https://app.example.com'],
    metadata: { customer_id: 'cus_123' },
  }),
});

if (!response.ok) throw new Error(`BeatAPI session failed: ${response.status}`);
const { data: session } = await response.json();

Allowed maximum durations are 15, 60, and 300 seconds. Reuse the same Idempotency-Key and request body when retrying the same create operation.

2. Connect in the browser

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

const camera = await navigator.mediaDevices.getUserMedia({
  video: true,
  audio: false,
});
const output = document.querySelector<HTMLVideoElement>('#realtime-output')!;

const client = createRealtimeClient({
  clientSecret: session.client_secret,
});

const unsubscribe = client.on('error', ({ error }) => {
  console.error(error?.message);
});

const connection = await client.connect({
  input: camera,
  output,
  initial: {
    prompt: 'Transform the scene into a cinematic neon world.',
    referenceImageUrl: 'https://media.example.com/character.png',
  },
});

await connection.set({
  prompt: 'Keep the motion and change the scene to watercolor.',
});

await connection.disconnect();
unsubscribe();
camera.getTracks().forEach((track) => track.stop());

initial and connection.set() accept a non-empty prompt, an HTTPS referenceImageUrl, or both. A reference image guides the generation; it does not replace the live input stream.

Events

Subscribe on the client before calling connect() when you need the complete lifecycle. connection.on() is also available after connection.

for (const event of ['connecting', 'connected', 'first_frame', 'disconnected', 'error'] as const) {
  client.on(event, ({ at, error }) => {
    console.log(event, at.toISOString(), error?.message);
  });
}

Browser requirements

• A secure context: HTTPS in production, or localhost during development.
• Browser support for navigator.mediaDevices.getUserMedia, MediaStream, WebRTC, and HTMLVideoElement playback.
• Camera permission from the user and an exact match between the page origin and the Session's allowed_origins.
• A current evergreen desktop or mobile browser. Test the exact devices, networks, and embedded-webview environments you support before release.

BeatAPI does not promise a fixed first-frame latency, frame rate, resolution, or device matrix through this package. Live output depends on browser, network, regional capacity, and the active realtime provider.

Security

• Keep permanent sk_... API keys on a trusted server.
• Do not log, persist, place in URLs, or reuse a Realtime client_secret after its Session closes or expires.
• Use exact HTTPS origins; wildcard origins are rejected.
• Ask for camera, face, likeness, IP, and reference-asset consent before capture.
• Stop local media tracks and close the BeatAPI Session when your experience ends.
• Realtime media is not automatically stored as a hosted MP4. If you use MediaRecorder, your application owns the recording, disclosure, retention, and deletion flow.

Troubleshooting

• Session expired or 401: create a new Session on your server and reconnect with its new client_secret.
• Capacity unavailable, 429, or 503: honor retry_after_seconds when present and retry with backoff.
• Origin not allowed: create the Session with the browser's exact origin, including scheme and port.
• Camera unavailable: confirm HTTPS/localhost, browser permissions, and that no other application is exclusively using the device.
• No output frame: listen for error, verify the input track remains live, and close the Session before creating a replacement.

Related tools

• Realtime Video guide
• OpenAPI contract
• @beatapi/realtime-cli for server-side Session diagnostics and lifecycle operations

Production access is limited while BeatAPI completes launch checks. Package publication and use remain subject to BeatAPI's applicable license and service terms.