REST API ReferenceEndpointsWorkflows

Voiceover to video

Creates a project from an uploaded voiceover file and generates a video with matching b-roll. Upload the voiceover via the files API first.

Authentication

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

Request

This endpoint expects an object.
fileIdstringRequired

Opaque file id of an uploaded voiceover audio file (e.g. vg_file_...). Upload the file first via POST /v1/files/upload.

visualStyleobjectRequired

Visual treatment 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.

languagestringOptional

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

captionStyleobject or nullOptional

Caption styling. Omit to use the default style with captions shown. Pass an object to override individual style fields (any omitted field uses the default). Pass null to hide captions entirely.

logoFileIdstring or nullOptional

Optional file id of an uploaded logo image to overlay on the video (e.g. vg_file_...). Upload the image first via POST /v1/files/upload. Only image files are accepted.

workflowAgentContextstringOptional

Optional production notes for the AI that builds the video — visual direction for how to illustrate the voiceover (e.g. on-screen code or text to display, specific b-roll to feature, or scene-by-scene staging). Never spoken; does not change the uploaded voiceover audio or its transcript.

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. Captions and a logo are set with the captionStyle and logoFileId request fields above; recommended remix actions here are SET_BACKGROUND_MUSIC for a music bed, ADD_TRANSITIONS to stamp transitions between sections and assets, and EDIT_WITH_AGENT for open-ended natural-language edits. See the Remix actions guide.

Response

Workflow run accepted.
workflowRunIdstring

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

projectIdstring
Id of the project created for this workflow run.
projectUrlstringformat: "uri"
URL to view the project in the VideoGen app.
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.