> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.videogen.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server. # Workflows > Start script-to-video, voiceover-to-video, or slideshow-to-video workflows via POST /v1/workflows/*. Poll GET /v1/workflows/runs/{workflowRunId} or subscribe to workflow_run.* webhooks. 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 30 seconds) without an editable project, use [`generate-video-clip`](/rest-api-reference/tools/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](/ai-styles) for example descriptions, `{ type: "STOCK" }` for stock footage, or `{ type: "AI_IMAGE", entityId }` for a saved visual-style entity). To direct the on-screen visuals yourself, pass timed `scenes` (see [Options](#options)). [Endpoint reference](/rest-api-reference/workflows/script-to-video) ### Voiceover to video Build a video around an audio file you provide. Upload the voiceover through the [Files API](/file-uploads) 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](/file-uploads)). To direct the on-screen visuals yourself, pass timed `scenes` (see [Options](#options)). [Endpoint reference](/rest-api-reference/workflows/voiceover-to-video) ### Slideshow to video Build a narrated walkthrough from an uploaded PDF or PowerPoint file. Upload the file through the [Files API](/file-uploads) first, then pass its `fileId`. VideoGen narrates each slide and adds transitions and captions. Override the per-slide narration with `slideScripts` (see [Options](#options)). [Endpoint reference](/rest-api-reference/workflows/slideshow-to-video) ### Prompt to video clip Generate one short AI video clip (1 to 30 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` (`LOW`, `STANDARD`, `HIGH`, or `MAX`). The generated clip is clamped to the selected quality's supported range. This workflow does not accept `remixActions`. For a standalone clip without a project, use [`generate-video-clip`](/rest-api-reference/tools/generate-video-clip). For longer narrated multi-scene videos, use [script to video](/rest-api-reference/workflows/script-to-video). [Endpoint reference](/rest-api-reference/workflows/prompt-to-video-clip) ## Options Workflows accept optional fields beyond their required input. Each applies only where it makes sense for that workflow. | Field | Applies to | Description | | ---------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `aspectRatio` | all | Output aspect ratio (e.g. 16:9). Defaults to 16:9. | | `durationSeconds` | prompt to video | Length in whole seconds (1 to 30, defaults to 10). Clamped to the selected quality's supported range. | | `imageFileIds` | prompt to video | File ids of uploaded reference images that guide the opening frame. Upload via the Files API first. | | `visualPacing` | script, voiceover | `FAST`, `MEDIUM`, or `SLOW`. Controls how quickly visuals change. Defaults to `MEDIUM`. | | `quality` | script, voiceover, prompt to video | For script/voiceover: image generation tier (`LOW`/`STANDARD`/`HIGH`) when `visualStyle.type` is `AI_IMAGE`. For prompt to video: video (and opening-frame) quality (`LOW`/`STANDARD`/`HIGH`/`MAX`). Defaults to `STANDARD`. | | `language` | script, voiceover, slideshow | Output language as a BCP-47 code (e.g. `en`, `es`, `fr`). Defaults to English. | | `slideScripts` | slideshow | Per-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. | | `voiceId` | script, slideshow | Catalog `displayName` (e.g. `Matilda`) or voice id from `GET /v1/resources/tts-voices`. A default voice is used when omitted. | | `voiceSpeed` | script, slideshow | Speech rate multiplier. Defaults to the voice's default. | | `actorEntityId` | script, slideshow | Recommended. ACTOR entity id (`vg_enti_...`) with at least one image reference. When set, narration is delivered by that actor avatar. Omit for a standard voiceover. | | `avatarQuality` | script, slideshow | Avatar generation quality tier: `LOW`, `STANDARD`, `HIGH`, or `MAX`. Applies when `actorEntityId` is set. Omit to use your account's default avatar quality. | | `featuredBRollFileIds` | script | File ids of uploaded images or videos to feature as b-roll. Upload via the Files API first. | | `captionStyle` | voiceover, slideshow | Caption 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. | | `logoFileId` | voiceover, slideshow | File 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. | | `remixActions` | script, voiceover, slideshow | Ordered 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](/remix-actions). | | `scenes` | script, voiceover | Optional timed scene descriptions guiding what to show on screen during absolute time ranges of the video, as `[{ startSeconds, endSeconds, description }]`. Ranges must be sorted by `startSeconds` and non-overlapping. Omit to let the workflow choose visuals automatically. | | `isOutputTemporary` | all | When `true`, the video's generated output files (AI images, video clips, voiceover audio, avatars, and any post-build remix-action media) are created as temporary: guaranteed available for 24 hours, then eligible for archival. Use this when your integration downloads or re-hosts the results itself. The project and its metadata are unaffected. Defaults to `false`. | To prepare an avatar, create or list an `ACTOR` with the Entities API, upload a portrait through the Files API, and add that file as an entity reference. Then pass the returned `entityId` as `actorEntityId`. ## Workflow run lifecycle | Method | Path | Purpose | | ------ | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/v1/workflows/runs` | List workflow runs, most recently created first (`selfOnly` scopes to the key owner). Cursor-paginated; see [Pagination](/pagination). | | `GET` | `/v1/workflows/runs/{workflowRunId}` | Poll run status (`pending`, `running`, `succeeded`, `failed`, `cancelled`). | | `POST` | `/v1/workflows/runs/{workflowRunId}/cancel` | Request cancellation of an in-progress workflow run (best-effort). | When a run succeeds, use `projectId` with the [Projects API](#projects-and-export) 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) ```typescript import { VideoGen, pollWorkflowRun } from "@videogen/sdk"; const client = new VideoGen({ apiKey: "sk_videogen_live_..." }); const { workflowRunId } = await client.workflows.scriptToVideo({ script: "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.", visualStyle: { type: "AI_IMAGE", aiStyle: "Loose watercolor illustration, visible brushstrokes, soft color bleeds, paper texture, muted palette. A clear uncluttered subject centered in the frame, occupying only the middle half of the image, with generous empty margins on all four sides, no background clutter.", }, visualPacing: "MEDIUM", quality: "HIGH", autoExport: true, remixActions: [ { type: "ENABLE_CAPTIONS" }, { type: "CONVERT_IMAGES_TO_VIDEOS", motionPrompt: "slow cinematic push-in", muteOutputVideos: true, quality: "HIGH", }, ], }); const run = await pollWorkflowRun({ client, workflowRunId }); console.log(run.downloadUrl); ``` ## Projects and export After a workflow completes, use the Projects API to list projects, fetch metadata, and render an MP4: | Method | Path | Purpose | | ------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/v1/projects` | List 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 (includes optional `projectUrl` for opening in the app). | | `POST` | `/v1/projects/{projectId}/export` | Start an export; returns `{ exportId }`. | | `GET` | `/v1/projects/{projectId}/exports/{exportId}` | Poll export status; `downloadUrl` when `status` is `succeeded`. | | `POST` | `/v1/projects/{projectId}/remix` | Apply ordered remix actions to a project. | | `GET` | `/v1/projects/{projectId}/remix-actions` | List remix actions for a project, with status and progress. | Use `pollProjectExport` (TS) / `poll_project_export` (Python) to wait for the MP4.