> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.videogen.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server.

# Generate motion graphic

POST https://api.videogen.io/v1/tools/generate-motion-graphic
Content-Type: application/json

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.

Reference: https://docs.videogen.io/rest-api-reference/tools/generate-motion-graphic

## Authentication

- `Authorization` header (bearer token, required) — API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

## Request

### Body (application/json)

This endpoint expects a 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` (list of string, optional) — 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` (list of string, optional) — 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, optional, 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, optional) — Aspect ratio for the generated motion graphic. Defaults to 16:9 when omitted.
- `transparentBackground` (boolean, optional, default: 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.
- `subToolModes` (MotionGraphicSubToolModes, optional) — 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.
- `numResults` (integer, optional, default: 1) — Number of output results to generate. Defaults to 1.
- `isOutputTemporary` (boolean, optional, default: 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.
- `hideFromUi` (boolean, optional, default: false) — 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.

- `toolExecutionId` (string, required) — Execution id (e.g. `vg_tool_...`).

## Types

### 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)

### MotionGraphicSubToolModes

Per-capability access modes for a motion graphic. Any omitted capability defaults to AUTO.

- `generateImages` (enum, optional) — Whether the motion graphic may generate images. Defaults to AUTO.
  - Allowed values: `AUTO`, `ENABLED`, `DISABLED`
- `generateVideoClips` (enum, optional) — Whether the motion graphic may generate video clips. Requires a paid plan. Defaults to AUTO.
  - Allowed values: `AUTO`, `ENABLED`, `DISABLED`
- `generateVoiceover` (enum, optional) — Whether the motion graphic may generate voiceover audio. Defaults to AUTO.
  - Allowed values: `AUTO`, `ENABLED`, `DISABLED`
- `searchStockMedia` (enum, optional) — Whether the motion graphic may search stock media. Defaults to AUTO.
  - Allowed values: `AUTO`, `ENABLED`, `DISABLED`

## Examples

**Request**

```json
{
  "prompt": "A dark terminal window that types out the command `npm run build` character by character, then shows a green success checkmark",
  "durationSeconds": 6,
  "aspectRatio": {
    "width": 16,
    "height": 9
  },
  "transparentBackground": true
}
```

**Response**

```json
{
  "toolExecutionId": "vg_tool_ccm3abc123defcm3xyz789ghi"
}
```

**SDK Code**

```typescript
import { VideoGen } from "@videogen/sdk";

const client = new VideoGen({ apiKey: "sk_videogen_live_..." });

await client.tools.generateMotionGraphic({
  prompt: "A dark terminal window that types out the command `npm run build` character by character, then shows a green success checkmark",
  durationSeconds: 6,
  aspectRatio: {
    width: 16,
    height: 9,
  },
  transparentBackground: true,
});
```

```python
from videogen import VideoGen

client = VideoGen(api_key="sk_videogen_live_...")

client.tools.generate_motion_graphic(
    prompt="A dark terminal window that types out the command `npm run build` character by character, then shows a green success checkmark",
    duration_seconds=6,
    aspect_ratio={
      "width": 16,
      "height": 9,
    },
    transparent_background=True,
)
```