Workflows

Workflows create a VideoGen project and run the full generation pipeline asynchronously. Each POST returns 202 Accepted with { workflowRunId, projectId, projectUrl }.

Poll GET /v1/workflows/runs/{workflowRunId} until status is terminal, or use the SDK helpers pollWorkflowRun (TS) / poll_workflow_run (Python). Subscribe to workflow_run.succeeded, workflow_run.failed, and workflow_run.cancelled webhook events for push notifications.

For a single short standalone clip (up to 15 seconds) without an editable project, use generate-video-clip instead. That tool automatically routes each request to a suitable video generation model.

Available workflows

Script to video

Build a narrated video from a script. VideoGen uses your text verbatim, then adds visuals, narration, and captions. This is the primary entry point: pass a script and a visualStyle ({ type: "AI_IMAGE", aiStyle } for AI-generated images, where aiStyle is a free-form description of the look; see AI styles for example descriptions, { type: "STOCK" } for stock footage, or { type: "ENTITY", entityId } for a saved visual-style entity). To direct the on-screen visuals yourself, pass timed scenes (see Options).

Endpoint reference

Voiceover to video

Build a video around an audio file you provide. Upload the voiceover through the Files API first, then pass its fileId and a visualStyle (same shape as script to video). VideoGen transcribes the audio and matches b-roll to the narration. To skip re-transcription and pin caption timing, attach a pre-computed transcript when you upload the audio (see File uploads). To direct the on-screen visuals yourself, pass timed scenes (see Options).

Endpoint reference

Slideshow to video

Build a narrated walkthrough from an uploaded PDF or PowerPoint file. Upload the file through the Files API first, then pass its fileId. VideoGen narrates each slide and adds transitions and captions. Override the per-slide narration with slideScripts (see Options).

Endpoint reference

Prompt to video clip

Generate one short AI video clip (1 to 15 seconds) from a text prompt, optionally guided by reference imageFileIds. VideoGen generates an opening frame from the prompt, then animates that frame into a video inside an editable project. Set the length with durationSeconds (defaults to 10) and the quality tier with quality (STANDARD or HIGH). This workflow does not accept remixActions. For a standalone clip without a project, use generate-video-clip. For longer narrated multi-scene videos, use script to video.

Endpoint reference

Options

Workflows accept optional fields beyond their required input. Each applies only where it makes sense for that workflow.

Workflow run lifecycle

When a run succeeds, use projectId with the Projects API to export or remix. You do not need projectUrl for an API-only flow.

About projectId and projectUrl

Every workflow creates a VideoGen project. Responses include both:

• projectId (vg_proj_...): the stable id for API calls (export, remix, metadata). Use this in integrations that never open the web app.
• projectUrl: a deep link to open the project in the VideoGen editor. Use it only when a person should review or manually edit the video in the app. Ignore it in a fully automated pipeline.

Access matches the dashboard: the project is available to members of your team and any project collaborators on that project, not to the public or to other teams.

Example (script to video)

1
import { VideoGen, pollWorkflowRun } from "@videogen/sdk";
2
3
const client = new VideoGen({ apiKey: "sk_videogen_live_..." });
4
5
const { workflowRunId } = await client.workflows.scriptToVideo({
6
  script:
7
    "Staying hydrated keeps your body and mind running at their best. Drinking enough water boosts your energy, focus, and mood. Keep a water bottle nearby and sip throughout the day.",
8
  visualStyle: {
9
    type: "AI_IMAGE",
10
    aiStyle: "loose watercolor illustration with visible brushstrokes and soft color bleeds",
11
  },
12
  visualPacing: "MEDIUM",
13
  quality: "HIGH",
14
  remixActions: [
15
    { type: "ENABLE_CAPTIONS" },
16
    {
17
      type: "CONVERT_IMAGES_TO_VIDEOS",
18
      motionPrompt: "slow cinematic push-in",
19
      muteOutputVideos: true,
20
      quality: "HIGH",
21
    },
22
  ],
23
});
24
25
const run = await pollWorkflowRun({ client, workflowRunId });
26
console.log(run.status, run.projectId);

Projects and export

After a workflow completes, use the Projects API to list projects, fetch metadata, and render an MP4:

Use pollProjectExport (TS) / poll_project_export (Python) to wait for the MP4.