Guides

Workflows

End-to-end video pipelines started with a single API call.

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.

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

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.

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

Options

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

FieldApplies toDescription
aspectRatioallOutput aspect ratio (e.g. 16:9). Defaults to 16:9.
visualPacingscript, voiceoverFAST, MEDIUM, or SLOW. Controls how quickly visuals change. Defaults to MEDIUM.
qualityscript, voiceoverImage generation quality tier for AI-generated visuals: LOW, STANDARD, or HIGH. Only applies when visualStyle.type is AI_IMAGE or ENTITY (STOCK is unaffected). Defaults to STANDARD.
languageallOutput language as a BCP-47 code (e.g. en, es, fr). Defaults to English.
slideScriptsslideshowPer-slide narration, in slide order, applied by index: each slide uses its matching entry, and an empty string makes that slide silent. Fewer entries than slides leaves the remaining slides silent; extra entries are ignored. Omit the field entirely to narrate each slide from its speaker notes in the uploaded file. Pass an empty array ([]) to guarantee no narration on any slide.
voiceIdscript, slideshowNarration voice from GET /v1/resources/tts-voices. A default voice is used when omitted.
voiceSpeedscript, slideshowSpeech rate multiplier. Defaults to the voice’s default.
avatarPresenterIdscript, slideshowPresenter id from GET /v1/resources/avatar-presenters to deliver the narration as a talking-head avatar. Pass your voiceId to that endpoint to list presenters sorted by best match for the voice. Omit for a standard voiceover.
featuredBRollFileIdsscriptFile ids of uploaded images or videos to feature as b-roll. Upload via the Files API first.
captionStylevoiceover, slideshowCaption styling. Omit to keep the default style with captions shown. Pass an object to override individual style fields (font, colors, background, alignment — any omitted field uses the default). Pass null to hide captions entirely. For script-to-video, style captions with an ENABLE_CAPTIONS remix action.
logoFileIdvoiceover, slideshowFile id of an uploaded logo image to overlay on the video. Upload the image via the Files API first. For script-to-video, add a logo with a SET_LOGO remix action.
remixActionsallOrdered list of edits applied after the video is built (background music, logo, captions, transitions, natural-language edits). Each runs asynchronously; the response returns one remix action id per entry. See Remix actions.

Workflow run lifecycle

MethodPathPurpose
GET/v1/workflows/runsList workflow runs, most recently created first (selfOnly scopes to the key owner). Cursor-paginated; see Pagination.
GET/v1/workflows/runs/{workflowRunId}Poll run status (pending, running, succeeded, failed, cancelled).
POST/v1/workflows/runs/{workflowRunId}/cancelRequest cancellation of an in-progress workflow run (best-effort).

When a run succeeds, open projectUrl in the VideoGen app or export the project via the Projects API.

Example (script to video)

1import { VideoGenClient, pollWorkflowRun } from "@videogen/sdk";
2
3const client = new VideoGenClient({ token: process.env.VIDEOGEN_API_KEY });
4
5const { 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
25const run = await pollWorkflowRun(client, workflowRunId);
26console.log(run.status, run.projectUrl);

Projects and export

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

MethodPathPurpose
GET/v1/projectsList projects (selfOnly=true scopes to the key owner; default is team-wide). API-created only by default; pass includeUiProjects=true to also include dashboard-created projects.
GET/v1/projects/{projectId}Project metadata and projectUrl.
POST/v1/projects/{projectId}/exportStart an export; returns { exportId }.
GET/v1/projects/{projectId}/exports/{exportId}Poll export status; downloadUrl when status is succeeded.

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