BeatAPI API Quick Start

BeatAPI gives one account and one server-side API key access to two product shapes:

Async Video Workflows create hosted Music Video or Ecommerce Video results that you poll or receive by webhook.

Realtime Video Sessions connect a browser MediaStream to live AI video generation through a short-lived Session and @beatapi/realtime.

Production API base URL:

https://api.beatapi.io

Authentication

Create a key in Dashboard → API Keys and keep it on a trusted server.

Never expose a permanent BeatAPI API key in browser or mobile client code. Realtime browsers receive only a short-lived client_secret created by your server.

Choose your integration

API	Input and control	Result
Music Video API	Audio, images, lyrics, prompt, storyboard options	Hosted video returned after async processing
Ecommerce Video API	Product images and a creative brief	Hosted product video returned after async processing
Realtime Video API	Browser `MediaStream`, prompt, optional reference image	Live WebRTC video output; no automatic hosted MP4

Async workflow quick start

Create a Music Video task:

Save data.id, then poll every 5–10 seconds:

Stop at succeeded or failed. A successful task exposes its hosted result in data.output.media[]. Add signed webhooks after polling works.

Realtime Video quick start

Realtime access is currently limited while launch checks are completed. The REST contract, SDK interface, billing lifecycle, and security boundary below are the release-candidate contract.

Create a short-lived Session from your server. Idempotency-Key makes network retries safe:

Install the browser SDK:

Connect with only the returned data.client_secret:

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

const camera = await navigator.mediaDevices.getUserMedia({ video: true });
const client = createRealtimeClient({ clientSecret: session.client_secret });
const connection = await client.connect({
  input: camera,
  output: document.querySelector('#realtime-output'),
  initial: { prompt: 'Transform the scene while preserving motion.' },
});

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

await connection.disconnect();

Use GET /v1/realtime/sessions/{session_id} to inspect the Session and DELETE on the same path to close it idempotently and release capacity. See the Realtime Video guide for lifecycle, billing, browser requirements, SDK events, privacy, and error handling.

Realtime CLI

The server-side CLI helps diagnose authentication and manage Sessions. It does not capture a camera or run WebRTC media.

The CLI reads the permanent key from BEATAPI_API_KEY; it does not accept a key argument.

Production checklist

Use the exact https://api.beatapi.io origin.

Generate a fresh idempotency key for each logical create operation and reuse it only for retries of that operation.

Keep permanent API keys on trusted servers and use exact HTTPS origins for Realtime Sessions.

Honor HTTP status codes, error code, request_id, and retry_after_seconds when supplied.

Close Realtime Sessions and stop local media tracks when the experience ends.

Use polling as the async source of truth; verify webhook signatures before parsing payloads.

Review the Privacy Policy and Terms of Service before capturing cameras, faces, likenesses, voices, or reference assets.

Quick Start

BeatAPI API Quick Start#

Authentication#

Choose your integration#

Async workflow quick start#

Realtime Video quick start#

Realtime CLI#