BeatAPI Realtime Video API
client_secret and uses @beatapi/realtime. Browser control requests stay on the BeatAPI transport endpoint; WebRTC media remains direct and is not relayed through BeatAPI.1. Create a session on your server
Idempotency-Key with the same body returns the same Session and the same short-lived client_secret; it does not reserve credits or capacity twice or invalidate a browser already using that credential.2. Connect in the browser
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 realtime = await client.connect({
input: camera,
output,
initial: {
prompt: 'Transform the person while preserving movement and lighting.',
referenceImageUrl: 'https://media.example.com/character.png',
},
});
await realtime.set({
referenceImageUrl: 'https://media.example.com/character.png',
prompt: 'Use a painterly style while preserving motion.',
});
await realtime.disconnect();connect, set, disconnect, and event subscriptions. set requires a non-empty prompt, an HTTPS reference image URL, or both. BeatAPI /v1/files or your own public HTTPS storage is recommended for reference images.Generation inputs
input: a browser MediaStream, usually from a camera or a captured media element.prompt: optional text that describes the requested live transformation.referenceImageUrl: an optional HTTPS image that guides character, clothing, object, or visual-style generation.Lifecycle and billing
ready, connecting, active, closed, failed, and expired.active and the selected fixed duration is fully settled. A Session that closes or expires without an accepted billing heartbeat is fully refunded. Billing activation is derived from the trusted transport lifecycle, not from a caller-supplied browser event. DELETE /v1/realtime/sessions/{session_id} is idempotent and releases capacity; expired sessions are also cleaned automatically.Browser security
allowed_origins; wildcards are rejected.sk_... API key in browser code.client_secret; discard it after the Session closes.realtime_session_expired, realtime_capacity_unavailable, and rate-limit errors by creating a new Session or retrying after the supplied delay.SDK events and cleanup
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 });
// connecting -> connected -> first_frame -> disconnected, or error
await connection.disconnect();
unsubscribe();
camera.getTracks().forEach((track) => track.stop());DELETE /v1/realtime/sessions/{session_id}; that operation is idempotent.Browser requirements
navigator.mediaDevices.getUserMedia, MediaStream, WebRTC, and HTMLVideoElement playback.allowed_origins.Errors and retries
code, and request_id together. When retry_after_seconds is present on a rate-limit or retryable capacity response, wait at least that long before retrying.realtime_capacity_unavailable: capacity is temporarily unavailable; retry with backoff.realtime_session_expired: create a new Session and reconnect.origin_not_allowed: recreate the Session with the browser's exact origin.invalid_client_secret: discard the credential and create a new Session from your server.transport_not_allowed: the private transport path or operation is not part of the SDK contract.CLI
@beatapi/realtime-cli manages server-side Session operations and diagnostics. It does not run camera or WebRTC media.BEATAPI_API_KEY, prints the API JSON envelope to stdout, and returns a non-zero exit code on failure.Privacy and acceptable use
MediaRecorder, your product controls the recording, disclosure, security, retention, sharing, and deletion flow.Availability
Modified at 2026-07-31 15:12:20