---
title: "Generate motion graphic"
method: POST
path: "/v1/tools/generate-motion-graphic"
tags: ["Tools"]
---

# Generate motion graphic

`POST /v1/tools/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](/workflows) (`POST /v1/workflows/script-to-video`) instead.

## Request body

- GenerateMotionGraphicRequest
  - `prompt` string, required — 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.
  - `fileIds` string[] — 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.
  - `entityIds` string[] — 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.
  - `durationSeconds` integer, nullable — 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).
  - `aspectRatio` AspectRatio — Aspect ratio as a width:height pair (e.g. 16 and 9 for 16:9). Not pixel dimensions.
    - `width` integer, required
    - `height` integer, required
  - `transparentBackground` boolean — 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.
  - `subToolModes` MotionGraphicSubToolModes — Per-capability access modes for a motion graphic. Any omitted capability defaults to AUTO.
    - `generateImages` 'AUTO' | 'ENABLED' | 'DISABLED' — Access mode for a motion graphic capability. AUTO uses the capability only when it is available on your plan (generated video clips require a paid plan). ENABLED forces the capability on and returns an upgrade error if your plan lacks it. DISABLED prevents the motion graphic from using the capability.
    - `generateVideoClips` 'AUTO' | 'ENABLED' | 'DISABLED' — Access mode for a motion graphic capability. AUTO uses the capability only when it is available on your plan (generated video clips require a paid plan). ENABLED forces the capability on and returns an upgrade error if your plan lacks it. DISABLED prevents the motion graphic from using the capability.
    - `generateVoiceover` 'AUTO' | 'ENABLED' | 'DISABLED' — Access mode for a motion graphic capability. AUTO uses the capability only when it is available on your plan (generated video clips require a paid plan). ENABLED forces the capability on and returns an upgrade error if your plan lacks it. DISABLED prevents the motion graphic from using the capability.
    - `searchStockMedia` 'AUTO' | 'ENABLED' | 'DISABLED' — Access mode for a motion graphic capability. AUTO uses the capability only when it is available on your plan (generated video clips require a paid plan). ENABLED forces the capability on and returns an upgrade error if your plan lacks it. DISABLED prevents the motion graphic from using the capability.
  - `numResults` integer — Number of output results to generate. Defaults to 1.
  - `isOutputTemporary` boolean — 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.
  - `hideFromUi` boolean — When true, generated files are hidden from the VideoGen Media page by default. They remain accessible through the API. Defaults to false.

## Response `202`

Execution accepted; poll until complete.

- StartToolExecutionResponse — Returned when a tool execution is started. Use `toolExecutionId` to poll for results or cancel.
  - `toolExecutionId` string, required — Execution id (e.g. `vg_tool_...`).

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/videogen/apis/videogen-api.md) · [All operations](https://skmtc.dev/videogen/apis/videogen-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/videogen/videogen-api/revisions/33dda0455d67/schema)