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:

import { VideoGen, pollExecutedTool } from "@videogen/sdk";
const client = new VideoGen({ apiKey: "sk_videogen_live_..." });
const { toolExecutionId } = await client.tools.generateVideoClip({
  prompt: "A sunset over a calm ocean, cinematic lighting",
});
const response = await pollExecutedTool({ client, toolExecutionId });
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.

const file = await client.files.enablePublicPreview({ fileId });
console.log(file.staticPublicPreviewSource?.url); // permanent public URL (any type)
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, simple <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. Simple HTML embed

When you only need a basic player, drop the permanent public MP4 URL into a native HTML5 <video> tag. This works in any CMS, static site, or email-adjacent landing page that accepts HTML.

<video
  controls
  playsinline
  preload="metadata"
  title="My VideoGen export"
  src="https://public.example/my-video.mp4"
>
  Your browser does not support HTML5 video.
  <a href="https://videogen.io" rel="noopener noreferrer">Created with VideoGen</a>
</video>

Use staticPublicPreviewSource.url (or staticPublicPreviewUrl from the export embed API) as the src. The title attribute helps accessibility and SEO. The fallback link credits VideoGen without requiring the adaptive player.

This serves a single MP4 file. It does not adapt quality to the viewer’s connection. For production embeds that need adaptive bitrate streaming, use the VideoGen Player below.

4. VideoGen Player (adaptive HLS embed)

The VideoGen Player packages decode your publicPlaybackId and render a playback-optimized embed: adaptive bitrate streaming over HLS, automatic quality switching as bandwidth changes, and branded controls tuned for exported VideoGen media.

Install the package for your stack:

npm install @videogen/player-react

Pass the publicPlaybackId from step 2 to the player:

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

5. Framework integration

The same publicPlaybackId works across popular web stacks. React apps use @videogen/player-react. Every other framework below mounts @videogen/player on a DOM node.

Next.js (App Router)

"use client";
import { VideoGenPlayer } from "@videogen/player-react";
export default function VideoEmbed() {
  return <VideoGenPlayer publicPlaybackId="vg_play_..." />;
}

Vue 3

<script setup>
import { onMounted, ref } from "vue";
import { createVideoGenPlayer } from "@videogen/player";
const containerRef = ref(null);
onMounted(() => {
  if (containerRef.value == null) {
    return;
  }
  createVideoGenPlayer(containerRef.value, {
    publicPlaybackId: "vg_play_...",
  });
});
</script>
<template>
  <div ref="containerRef" />
</template>

Svelte

<script>
  import { onMount } from "svelte";
  import { createVideoGenPlayer } from "@videogen/player";
  let container;
  onMount(() => {
    if (container == null) {
      return;
    }
    createVideoGenPlayer(container, {
      publicPlaybackId: "vg_play_...",
    });
  });
</script>
<div bind:this={container} />

Angular

import { AfterViewInit, Component, ElementRef, ViewChild } from "@angular/core";
import { createVideoGenPlayer } from "@videogen/player";
@Component({
  selector: "app-video-embed",
  template: `<div #playerContainer></div>`,
})
export class VideoEmbedComponent implements AfterViewInit {
  @ViewChild("playerContainer") playerContainer!: ElementRef<HTMLDivElement>;
  ngAfterViewInit(): void {
    createVideoGenPlayer(this.playerContainer.nativeElement, {
      publicPlaybackId: "vg_play_...",
    });
  }
}

Static HTML (module script)

<div id="player-container"></div>
<script type="module">
  import { createVideoGenPlayer } from "@videogen/player";
  const container = document.getElementById("player-container");
  if (container == null) {
    throw new Error("Missing element #player-container");
  }
  createVideoGenPlayer(container, {
    publicPlaybackId: "vg_play_...",
  });
</script>

Controlling playback (React)

The React component exposes a ref with playback controls:

import { useRef } from "react";
import { VideoGenPlayer, VideoGenPlayerHandle } from "@videogen/player-react";
function VideoWithControls() {
  const playerRef = useRef<VideoGenPlayerHandle>(null);
  return (
    <>
      <VideoGenPlayer ref={playerRef} publicPlaybackId="vg_play_..." />
      <button onClick={() => playerRef.current?.play()}>Play</button>
      <button onClick={() => playerRef.current?.pause()}>Pause</button>
    </>
  );
}

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.):

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