Generate motion graphic

Generate an animated motion graphic video from a text prompt. This is an experimental, fully agentic alternative to a video workflow: VideoGen plans the animation, optionally generates or fetches supporting media, and renders a self-contained animated clip. It is especially well suited to precise text animations (e.g. a typing effect, animated captions, kinetic typography, lower thirds) that are hard to express with stock or generated footage. Optionally pass uploaded fileIds for reference media and entityIds for actors, products, or visual styles the animation should use. This endpoint returns one standalone video. For longer, narrated, multi-scene videos, use a video workflow such as Script to video (POST /v1/workflows/script-to-video) instead.

Authentication

AuthorizationBearer

API key from app.videogen.io/api. The full key is only shown once when you create it.

Request

This endpoint expects an object.

promptstringRequired

Text prompt describing the animated motion graphic to generate. Describe the on-screen elements, any text and how it should animate, and the overall motion in plain language.

fileIdslist of stringsOptional

Optional file ids of uploaded reference media (images, videos, or audio) the motion graphic may display or animate (e.g. ["vg_file_..."]). Upload files first via POST /v1/files/upload, then pass the returned ids here.

entityIdslist of stringsOptional

Optional actor, product, or visual-style entity ids (e.g. ["vg_enti_..."]). The motion graphic uses each entity as identity/reference the same way in-app motion graphic generation does. Can be combined with fileIds. Mentions in prompt are also collected. A missing id returns not found; an inaccessible id returns a permission error.

durationSecondsinteger or nullOptional1-300

Desired length of the motion graphic in seconds, a whole number between 1 and 300. When omitted, the duration is chosen automatically to fit the prompt (recommended).

aspectRatioobjectOptional

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

transparentBackgroundbooleanOptionalDefaults to true

When true, renders the motion graphic with a transparent background as a WebM video suitable for overlaying on other video or images. Set to false for an opaque MP4. Defaults to true.

subToolModesobjectOptional

Optional per-capability controls for the media the motion graphic may generate or fetch (generated images, generated video clips, generated voiceover, and stock media search). Each capability is AUTO, ENABLED, or DISABLED. Omit to use AUTO for every capability.

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