Immersive AI Video Generator SDK

Upload video → choose scenes → convert → check results → create final video

There are two ways to use it:

• Ready-made React components — drop in the complete tool (upload page, scene picker, player, final video) with a few lines. No third-party branding, and you can match its colours to your site.
• The JavaScript API — build your own interface on the same calls the components use.

Both run in the browser with no backend of your own and no secret key. Detected cuts are used as they are; changing a scene's fill, AI prompt or cut points is optional.

Prerequisites

1. A BuildVR enterprise plan.
2. A publishable client key (PUB key). Its client_id is the only credential the SDK uses.
3. Your website's domain on that key's allowed domains, for example www.example.com, plus your local development host such as localhost:5173.

Step 1 — Create API Credentials

After your plan is active, generate a publishable key from your profile:

https://buildvr.ai/profile/api-credentials

Add Allowed Domains

BuildVR only accepts requests from the browser's real Origin, which page scripts can't fake, and only if that origin is on the key's allowed list. Add every host that will load the SDK, separated by commas:

localhost:3000, localhost:5173, www.example.com

Save Your Client ID

Copy the key's client ID. You'll pass it as clientId. It can safely appear in your page source, but keep it in an environment variable so you can rotate it easily. Everything users do through the SDK (uploads, conversions, credits) is billed to the account that owns the key.

NEXT_PUBLIC_VIDEO_CLIENT_ID=YOUR_CLIENT_ID

Step 2 — Install the Package

npm install @buildvr/immersive-ai-video-generator

yarn add @buildvr/immersive-ai-video-generator

pnpm add @buildvr/immersive-ai-video-generator

The React components need React 18 or later (react and react-dom). Without a bundler, load the API from a CDN:

<script src="https://unpkg.com/@buildvr/immersive-ai-video-generator@0.3"></script>
<script>
  // window.SceneReview
  SceneReview.init({ clientId: "YOUR_CLIENT_ID" });
</script>

Changelog and release notes: npmjs.com/package/@buildvr/immersive-ai-video-generator

Step 3 — Add the Drop-in Components

Everything in one component

ImmersiveVideoGenerator gives your users the whole flow: the upload page, the job page with scene picking, conversion and the final video download, and a list of earlier jobs. It connects with clientId itself, so you don't need to call init(). Import the stylesheet once.

import { ImmersiveVideoGenerator } from "@buildvr/immersive-ai-video-generator/panel";
import "@buildvr/immersive-ai-video-generator/panel/style.css";

export default function VideoToolPage() {
  return (
    <ImmersiveVideoGenerator
      clientId={process.env.NEXT_PUBLIC_VIDEO_CLIENT_ID}
      onComplete={(job) => console.log("Final video:", job.output_url)}
    />
  );
}

To keep the open job in the URL so reloads and shared links work, control it yourself:

const [jobId, setJobId] = useState(new URLSearchParams(location.search).get("job"));

<ImmersiveVideoGenerator
  clientId={process.env.NEXT_PUBLIC_VIDEO_CLIENT_ID}
  jobId={jobId}                 // null = upload page
  onJobChange={(id) => {        // job created or opened, or "New video" clicked
    setJobId(id);
    history.pushState(null, "", id ? `?job=${id}` : location.pathname);
  }}
/>

One component per page (Next.js and other routers)

If your site has routing, use an upload page and a job page. A Next.js App Router example:

"use client";
import { useRouter } from "next/navigation";
import { CreateVideo } from "@buildvr/immersive-ai-video-generator/panel";
import "@buildvr/immersive-ai-video-generator/panel/style.css";

export default function NewVideoPage() {
  const router = useRouter();
  return (
    <CreateVideo
      clientId={process.env.NEXT_PUBLIC_VIDEO_CLIENT_ID}
      onCreated={(jobId) => router.push(`/video/${jobId}`)}
    />
  );
}

"use client";
import { use } from "react";
import { useRouter } from "next/navigation";
import { VideoJob } from "@buildvr/immersive-ai-video-generator/panel";
import "@buildvr/immersive-ai-video-generator/panel/style.css";

export default function VideoJobPage({ params }) {
  const { jobId } = use(params);
  const router = useRouter();
  return (
    <VideoJob
      clientId={process.env.NEXT_PUBLIC_VIDEO_CLIENT_ID}
      jobId={jobId}
      onNewVideo={() => router.push("/video")}
    />
  );
}

The components are already marked as client components. With React Router, Vue Router or any other router the pattern is the same: navigate in onCreated, and pass the job ID from the URL to VideoJob.

Component Props

All components accept clientId, plus optional apiBase, className and style. If your page already called SceneReview.init(), you can leave out clientId.

<ImmersiveVideoGenerator />

<CreateVideo /> — the upload page

<VideoJob /> — one job, from scenes to final video

<JobsList /> — recent jobs for your own jobs page

Matching Your Brand

The components use a dark theme. Override these CSS variables with style or className:

<ImmersiveVideoGenerator
  clientId={process.env.NEXT_PUBLIC_VIDEO_CLIENT_ID}
  style={{ "--cyan": "#a78bfa", "--cyanStrong": "#8b5cf6", "--bg": "#0b0b12" }}
/>

How a Job Works

After step 6 starts, the job is locked and no more edits are possible.

Fill modes

Cylindrical video is much wider than the source, so the extra space has to be filled:

Building Your Own UI with the API

All methods are on the default export, SceneReview. Every method except init() resolves to a result object and never throws on API errors.

import SceneReview from "@buildvr/immersive-ai-video-generator";

// 1. Connect once per page load. Throws if the key, domain or plan is wrong.
await SceneReview.init({ clientId: "YOUR_CLIENT_ID" });

// 2. Upload. Creates the job and starts scene detection.
const upload = await SceneReview.uploadVideo(file, {
  name: "Beach trip",
  fillMode: "ai",
  targetResolution: "4k",
  onProgress: ({ stage, progress }) => console.log(stage, Math.round(progress * 100) + "%"),
});
if (!upload.success || !upload.job_id) throw new Error(upload.error);
const jobId = upload.job_id;

// 3. Wait for scene detection.
let review = await waitFor(jobId, (r) => r.stage === "review" && r.scenes.length);

// 4. Choose scenes (here: all of them) and convert them.
const picked = review.scenes.map((s) => s.id);
await SceneReview.convertScenes(jobId, picked);

// 5. Wait until every picked scene has a converted output.
review = await waitFor(jobId, (r) =>
  r.scenes.filter((s) => picked.includes(s.id)).every((s) => s.output_url && s.status === "completed"));

// 6. Stitch the final video and wait for it.
await SceneReview.createFinalVideo(jobId, picked);
let job;
do {
  await sleep(5000);
  ({ job } = await SceneReview.getJob(jobId));
} while (job && !["completed", "failed"].includes(job.status));

console.log("Final video:", job.output_url);

// Helpers
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
async function waitFor(jobId, done) {
  for (;;) {
    const res = await SceneReview.getReview(jobId);
    if (res.success && done(res.review)) return res.review;
    await sleep(3000);
  }
}

Methods

The full reference, including the review and Scene data shapes and cut-editing rules, is in the package README.

Handling Errors

Every call except init() resolves to an object like this on failure:

{ success: false, status_code: 409, error: "Human-readable message", code: "machine_readable_code", ...details }

Account-level failures

Polling

There are no webhooks yet, so poll for progress. The drop-in components do this for you.

Billing

• Uploads and conversions count against the plan of the account that owns the client key.
• When the plan's quota is used up, extra storage and processing minutes are paid automatically from the account's wallet credits, with no confirmation step. Calls fail with quota_exceeded or insufficient_credits only when the wallet runs short.
• You're billed only for scenes in the final video. Scenes left out are refunded when the final video is made.
• Each scene includes free reprocesses (init().scene_review.free_reprocesses_per_scene). After those, reprocesses use wallet credits at the scene's length.

Troubleshooting

Can I call this from my server (Node)?

No. The SDK depends on the browser's Origin header and uses XMLHttpRequest and <video> for uploads. For server-to-server work, use the Video Processing API with a secret key.

Which browsers are supported?

Current versions of Chrome, Edge, Safari and Firefox.

Next Steps