REST API ReferenceEndpointsWorkflows

Script to video

Creates a project and generates a narrated video from a prompt or script. Returns immediately with a workflow run id; poll or subscribe to webhooks for completion.

Authentication

AuthorizationBearer
API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

Request

This endpoint expects an object.
scriptstringRequired

The narration script, used verbatim. This exact text is narrated and turned into a video — it is not rewritten or expanded.

visualStyleobjectRequired

Visual style for the generated b-roll.

aspectRatioobjectOptional

Aspect ratio as a width:height pair (e.g. 16 and 9 for 16:9). Not pixel dimensions.

visualPacingenumOptionalDefaults to MEDIUM

How quickly visuals change. FAST shows more, shorter shots; SLOW holds each visual longer. Defaults to MEDIUM.

qualityenumOptional

Image generation quality tier for AI-generated visuals. Optional; when omitted, your workspace’s Default AI quality for images is used (change it at https://app.videogen.io/settings/account). Only applies when visualStyle.type is AI_IMAGE or ENTITY; STOCK pulls existing footage and is unaffected.

languagestringOptional

Output language as a BCP-47 code (e.g. en, es, fr). Defaults to English.

voiceIdstring or nullOptional

Voice id from GET /v1/resources/tts-voices (e.g. vg_voic_...). A default voice is used when omitted. Any voice may be used here, including voices where supportsDirectToolExecution is false.

voiceSpeeddoubleOptional0.5-2

Speech rate multiplier, between 0.5 (half speed) and 2 (double speed). Defaults to the voice’s default speed.

avatarPresenterIdstring or nullOptional

Optional avatar presenter id from GET /v1/resources/avatar-presenters (e.g. vg_pres_...). When set, the narration is delivered by a talking-head presenter avatar. Pass your voiceId to that endpoint to list presenters sorted by best match for the voice. Omit for a standard voiceover with no presenter.

featuredBRollFileIdslist of stringsOptional

Optional file ids of images or videos to feature as b-roll (e.g. ["vg_file_..."]). Upload files first via POST /v1/files/upload. Only image and video files are accepted.

workflowAgentContextstringOptional

Optional production notes for the AI that builds the video — visual direction that should not appear in the spoken narration (e.g. on-screen code or text to display, specific b-roll to feature, or scene-by-scene staging). Never spoken; keep the narration itself in script.

sceneslist of objectsOptional

Optional timed scene descriptions guiding what to show on screen during each absolute time range of the video. Ranges must be sorted by startSeconds and non-overlapping. Omit to let the workflow choose visuals automatically.

remixActionslist of objectsOptional

Optional edits applied to the project after the video is built, in order. Each action runs asynchronously; the response returns one remix action id per action. Recommended for script-to-video: ENABLE_CAPTIONS to show and style captions, CONVERT_IMAGES_TO_VIDEOS to animate still images into clips, ADD_TRANSITIONS to stamp transitions between sections, and SET_LOGO to overlay a logo (this workflow has no native caption-style or logo fields). See the Remix actions guide.

isOutputTemporarybooleanOptionalDefaults to false

When true, the video’s generated OUTPUT files (AI images, video clips, voiceover audio, avatars) are created as temporary: guaranteed available for 24 hours, after which they may be archived and later deleted. This also covers files produced by post-build remix actions (e.g. generated background music, image-to-video conversions). Use this when your integration downloads or re-hosts the results itself and does not need VideoGen to retain them. The project and its metadata are unaffected. Defaults to false.

Response

Workflow run accepted.
workflowRunIdstring

Opaque workflow run id (e.g. vg_work_...).

projectIdstring

Id of the project created for this workflow run (e.g. vg_proj_...).

projectUrlstringformat: "uri"

Deep link to open this project in the VideoGen web editor. Not required for an API-only integration: store projectId and use the Projects API (export, remix, metadata). Use projectUrl when a person should open the project in the app to review or edit it manually. The project is visible only to members of your team and any project collaborators, the same access model as a project created in the dashboard.

remixActionIdslist of strings

Opaque remix action ids (e.g. vg_rmix_...), one per remixActions entry in request order. Empty when no remix actions were requested. Each runs after the video is built; poll GET /v1/projects/{projectId}/remix-actions.