Embedding videos

VideoGen files are private by default. To share or embed them, call enable public preview on the file. That always returns a permanent public URL (staticPublicPreviewSource) for any file type — images, audio, video, PDFs, and more.

For video and audio embeds, the same call also registers a public playback ID (publicPlaybackId) once streaming is ready. Pass that ID to @videogen/player or @videogen/player-react for a branded player with adaptive streaming.

1. Generate a video

Use any video tool (e.g. generateVideoClip) and wait for the execution to complete:

1
import { VideoGenClient, pollExecutedTool } from "@videogen/sdk";
2
3
const client = new VideoGenClient({ token: "YOUR_API_KEY" });
4
5
const { toolExecutionId } = await client.tools.generateVideoClip({
6
  prompt: "A sunset over a calm ocean, cinematic lighting",
7
});
8
9
const response = await pollExecutedTool(client, toolExecutionId);
10
const fileId = response.results[0].fileId;

2. Enable public preview

Call the enable public preview endpoint on the generated file. This works for any file type — not just video and audio.

1
const file = await client.files.enablePublicPreview({ fileId });
2
3
console.log(file.staticPublicPreviewSource?.url); // permanent public URL (any type)
4
console.log(file.publicPlaybackId); // "vg_play_..." (video/audio embeds, when ready)

The response includes:

Which URL should I use?

• Embedded video or audio player → publicPlaybackId with @videogen/player (adaptive streaming, branded controls).
• Direct permanent link (image in a blog post, PDF download, <video src> fallback, etc.) → staticPublicPreviewSource.url.

For video and audio, the endpoint starts a streaming upload if one does not exist yet and polls briefly for the embed playback id. If streaming is still processing, use pollPublicPreview / poll_public_preview from the SDK (or poll GET /v1/files/{fileId}) until staticPublicPreviewSource and publicPlaybackId are ready.

To disable public preview later, call POST /v1/files/{fileId}/disable-public-preview. This removes the public URL copy and revokes embed streaming access.

3. Install the player

Choose the package for your stack:

$
npm install @videogen/player-react

4. Embed the video

Pass the publicPlaybackId from step 2 to the player:

1
import { VideoGenPlayer } from "@videogen/player-react";
2
3
function VideoEmbed() {
4
  return <VideoGenPlayer publicPlaybackId="vg_play_..." autoPlay muted />;
5
}

Controlling playback (React)

The React component exposes a ref with playback controls:

1
import { useRef } from "react";
2
import { VideoGenPlayer, VideoGenPlayerHandle } from "@videogen/player-react";
3
4
function VideoWithControls() {
5
  const playerRef = useRef<VideoGenPlayerHandle>(null);
6
7
  return (
8
    <>
9
      <VideoGenPlayer ref={playerRef} publicPlaybackId="vg_play_..." />
10
      <button onClick={() => playerRef.current?.play()}>Play</button>
11
      <button onClick={() => playerRef.current?.pause()}>Pause</button>
12
    </>
13
  );
14
}

Using the raw HLS URL

If you prefer to use your own player, the publicHlsUrl field from the enable public preview response is a standard HLS stream URL that works with any HLS-compatible player (hls.js, Video.js, native Safari, etc.):

1
const file = await client.files.enablePublicPreview({ fileId });
2
3
// Use with any HLS player
4
const hlsUrl = file.publicHlsUrl; // "https://stream.media.videogen.io/..."