REST API ReferenceEndpointsTools

Generate video clip

Generate a single short video clip (up to 30 seconds) from a text prompt, optionally guided by an opening-frame still, reference images, videos, and audio. At least one of `prompt`, `startFrameFileId`, `imageFileIds`, `videoFileIds`, `audioFileIds`, or `spokenDialogue` must be provided. VideoGen automatically routes each request to the most effective state-of-the-art video model for your inputs and settings, so you don't pick a model. This endpoint returns one standalone clip. For longer, higher-quality, professionally edited videos with narration, captions, music, and multiple scenes, use a video workflow such as [Script to video](/workflows) (`POST /v1/workflows/script-to-video`) instead.

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

Text prompt describing the video to generate. Optional when reference media, startFrameFileId, or spokenDialogue is provided. Describe the video in plain language; any reference media you provide is incorporated automatically.

startFrameFileIdstringOptional

Optional file id of the opening-frame still (e.g. vg_file_...). Upload first via POST /v1/files/upload. When set, this image is the first frame of the clip. If the same id also appears in imageFileIds, it is used only as the opening frame and dropped from the reference list. Can be the only input (prompt optional).

imageFileIdslist of stringsOptional

Optional file ids of reference images (e.g. ["vg_file_..."]). Upload files first via POST /v1/files/upload, then pass the returned ids here. When provided, the images are used as visual guidance. To animate a specific still as the opening frame, pass it as startFrameFileId instead.

videoFileIdslist of stringsOptional

Optional file ids of reference videos (e.g. ["vg_file_..."]). Upload files first via POST /v1/files/upload, then pass the returned ids here. They are used as motion or style guidance for the generated video.

audioFileIdslist of stringsOptional

Optional file ids of reference audio clips (e.g. ["vg_file_..."]) used for lip-sync from that recording. Upload files first via POST /v1/files/upload, then pass the returned ids here. To have the model speak a line it generates itself, pass spokenDialogue instead (or in addition).

spokenDialoguestringOptional

Optional exact line the subject should speak as native, lip-synced speech in the generated clip. The model synthesizes the voice from this text. Can be the only input. Combine with a visual prompt, startFrameFileId, or reference media. Combine with audioFileIds when you also have a reference recording.

voiceDescriptionstringOptional

Optional natural-language description of the voice that speaks spokenDialogue (for example, a warm, confident young man’s voice). Used when spokenDialogue is set. When omitted, a clear natural voice is used.

generateAudiobooleanOptionalDefaults to false
When true, the generated video is guaranteed to include audio. When false, audio may still be present. Defaults to false.
suppressBackgroundMusicbooleanOptionalDefaults to false

When true, the generated clip will not include a musical soundtrack. Spoken dialogue and environmental sound are still allowed. Use this when you will add background music separately (for example at the project level). Defaults to false.

durationSecondsinteger or nullOptional1-30

Desired clip length in seconds. A whole number between 1 and 30. Defaults to 6 when omitted. The generated clip is clamped to the selected quality’s supported range. This endpoint produces a single short clip. For longer, multi-scene, professionally edited videos, use a video workflow such as POST /v1/workflows/script-to-video.

aspectRatioobjectOptional

Aspect ratio for the generated video. Defaults to 16:9 when omitted.

qualityenumOptional

Video generation quality tier (LOW, STANDARD, HIGH, or MAX). Optional; when omitted, your account’s Default AI quality for video is used (change it at https://app.videogen.io/settings/account).

contentPolicyConfigobjectOptional

Controls how content-policy rejections are handled during generation.

watermarkModeenumOptionalDefaults to AUTO

Controls whether the VideoGen watermark is applied to the output. AUTO applies the watermark unless you have a Pro plan. VIDEO_GEN always applies it. NONE removes the watermark (requires Pro; returns an error if you don’t have it).

numResultsintegerOptional1-100Defaults to 1
Number of output results to generate. Defaults to 1.
isOutputTemporarybooleanOptionalDefaults to false

When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false.

hideFromUibooleanOptionalDefaults to false
When true, generated files are hidden from the VideoGen Media page by default. They remain accessible through the API. Defaults to false.

Response

Execution accepted; poll until complete.

toolExecutionIdstring

Execution id (e.g. vg_tool_...).