> 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 video clip

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

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.

Reference: https://docs.videogen.io/rest-api-reference/tools/generate-video-clip

## 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 GenerateVideoClipRequest.

- `prompt` (string, optional) — 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.
- `startFrameFileId` (string, optional) — 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).
- `imageFileIds` (list of string, optional) — 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.
- `videoFileIds` (list of string, optional) — 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.
- `audioFileIds` (list of string, optional) — 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).
- `spokenDialogue` (string, optional) — 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.
- `voiceDescription` (string, optional) — 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.
- `generateAudio` (boolean, optional, default: false) — When true, the generated video is guaranteed to include audio. When false, audio may still be present. Defaults to false.
- `suppressBackgroundMusic` (boolean, optional, default: 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.
- `durationSeconds` (integer, optional, nullable) — Optional clip length in whole seconds (1 to 30). Omit or pass null for Auto (duration is estimated at generate time so spoken text or the visual beat fits, clamped to the selected quality's supported range). When set, that length is used as-is. 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`.
- `aspectRatio` (AspectRatio, optional) — Aspect ratio for the generated video. Defaults to 16:9 when omitted.
- `quality` (enum, optional) — 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).
  - Allowed values: `LOW`, `STANDARD`, `HIGH`, `MAX`
- `contentPolicyConfig` (ContentPolicyConfig, optional) — Controls how content-policy rejections are handled during generation.
- `watermarkMode` (enum, optional, default: 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).
  - Allowed values: `NONE`, `VIDEO_GEN`, `AUTO`
- `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)

### ContentPolicyConfig

Controls how content-policy rejections are handled during generation.

- `maxPromptRewrites` (integer, optional, default: 0) — Maximum number of automatic prompt rewrites to attempt after a content-policy rejection before failing. Must be an integer between 0 and 4. 0 (the default) fails on the first rejection and returns the moderation error so you can revise the prompt yourself. Higher values let the request automatically rephrase and retry the prompt.

## Examples

### Example_0

**Request**

```json
{
  "prompt": "A serene mountain landscape at sunrise with a flowing river and birds flying",
  "generateAudio": true,
  "durationSeconds": 6,
  "quality": "STANDARD"
}
```

**Response**

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

**SDK Code**

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

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

await client.tools.generateVideoClip({
  prompt: "A serene mountain landscape at sunrise with a flowing river and birds flying",
  quality: "STANDARD",
  generateAudio: true,
  durationSeconds: 6,
});
```

```python Example_0
from videogen import VideoGen

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

client.tools.generate_video_clip(
    prompt="A serene mountain landscape at sunrise with a flowing river and birds flying",
    quality="STANDARD",
    generate_audio=True,
    duration_seconds=6,
)
```

### Example_1

**Request**

```json
{
  "prompt": "Apply a cinematic color grade with enhanced contrast and film grain",
  "videoFileIds": [
    "vg_file_jzosm31OGi-bPE1eb3qLnA"
  ],
  "quality": "STANDARD"
}
```

**Response**

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

**SDK Code**

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

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

await client.tools.generateVideoClip({
  prompt: "Apply a cinematic color grade with enhanced contrast and film grain",
  quality: "STANDARD",
  videoFileIds: [
    "vg_file_jzosm31OGi-bPE1eb3qLnA",
  ],
});
```

```python Example_1
from videogen import VideoGen

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

client.tools.generate_video_clip(
    prompt="Apply a cinematic color grade with enhanced contrast and film grain",
    quality="STANDARD",
    video_file_ids=[
      "vg_file_jzosm31OGi-bPE1eb3qLnA",
    ],
)
```

### Example_2

**Request**

```json
{
  "prompt": "Create a dynamic video animation from this serene mountain landscape image, adding subtle cloud movements and ambient nature sounds.",
  "imageFileIds": [
    "vg_file_obLD1OX2eJCrEs0071Z4kA"
  ],
  "generateAudio": true,
  "quality": "STANDARD"
}
```

**Response**

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

**SDK Code**

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

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

await client.tools.generateVideoClip({
  prompt: "Create a dynamic video animation from this serene mountain landscape image, adding subtle cloud movements and ambient nature sounds.",
  quality: "STANDARD",
  generateAudio: true,
  imageFileIds: [
    "vg_file_obLD1OX2eJCrEs0071Z4kA",
  ],
});
```

```python Example_2
from videogen import VideoGen

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

client.tools.generate_video_clip(
    prompt="Create a dynamic video animation from this serene mountain landscape image, adding subtle cloud movements and ambient nature sounds.",
    quality="STANDARD",
    generate_audio=True,
    image_file_ids=[
      "vg_file_obLD1OX2eJCrEs0071Z4kA",
    ],
)
```