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

# Prompt to video clip

POST https://api.videogen.io/v1/workflows/prompt-to-video-clip
Content-Type: application/json

Creates a project from a text prompt and generates one short AI video clip (up to 30 seconds). VideoGen first generates an opening frame from the prompt (optionally guided by reference images), then animates that frame into a video. Returns immediately with a workflow run id; poll or subscribe to webhooks for completion. For a standalone clip without an editable project, use `POST /v1/tools/generate-video-clip` instead. For longer narrated multi-scene videos, use `POST /v1/workflows/script-to-video`. The generated clip is clamped to the selected quality's supported range.

Reference: https://docs.videogen.io/rest-api-reference/workflows/prompt-to-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 PromptToVideoClipRequest.

- `prompt` (string, required) — Text prompt describing the video to generate (e.g. `A golden retriever running through a sunlit meadow in slow motion, cinematic`).
- `imageFileIds` (list of string, optional) — Optional ids of previously uploaded reference images (e.g. `vg_file_...`) that guide the opening frame. Upload files via `POST /v1/files/upload` first.
- `durationSeconds` (integer, optional) — Desired clip length in whole seconds (1 to 30). Defaults to 10. The generated clip is clamped to the selected quality's supported range.
- `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`). Also used for the opening-frame image. 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`
- `isOutputTemporary` (boolean, optional, default: false) — When true, the generated OUTPUT files (the opening-frame image and the video clip) are created as temporary: guaranteed available for 24 hours, after which they may be archived and later deleted. Use this when your integration downloads or re-hosts the results itself and does not need VideoGen to retain them. The project and its metadata are unaffected. Defaults to false.
- `hideFromUi` (boolean, optional, default: false) — When true, the project is hidden from Home and Projects by default, and generated files are hidden from the Media page. The project and files remain accessible through the API. Defaults to false.
- `autoExport` (boolean, optional, default: false) — When true, VideoGen exports an MP4 after the video is built (and after any `remixActions` on this request finish). The workflow run stays `running` until that export succeeds or fails. On success, poll `GET /v1/workflows/runs/{workflowRunId}` and use `downloadUrl`. Defaults to false.
- `exportOptions` (ExportProjectRequest, optional) — Export settings used when `autoExport` is true. Ignored when `autoExport` is false. Omitted fields use the same defaults as `POST /v1/projects/{projectId}/export`.

## Response

### 202

Workflow run accepted.

- `workflowRunId` (string, required) — Opaque workflow run id (e.g. `vg_work_...`).
- `projectId` (string, required) — Id of the project created for this workflow run (e.g. `vg_proj_...`).
- `projectUrl` (string, required) — Deep link to open this project in the VideoGen web editor. Not required for an API-only integration: store `projectId` and use the Projects API (export, remix, metadata). Use `projectUrl` when a person should open the project in the app to review or edit it manually. The project is visible only to members of your team and any project collaborators, the same access model as a project created in the dashboard.
- `remixActionIds` (list of string, required) — Opaque remix action ids (e.g. `vg_rmix_...`), one per `remixActions` entry in request order. Empty when no remix actions were requested. Each runs after the video is built; poll `GET /v1/projects/{projectId}/remix-actions`.

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

### ExportProjectRequest

- `quality` (enum, optional) — Vertical resolution tier for the rendered MP4.
  - Allowed values: `STANDARD`, `HIGH`, `FULL_HIGH`, `ULTRA_HIGH`
- `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`
- `endScreenMode` (enum, optional, default: AUTO) — Controls whether a short 'Made with VideoGen' end screen is appended to the output. `AUTO` appends it unless you have a Pro plan. `VIDEO_GEN` always appends it. `NONE` removes it (requires Pro; returns an error if you don't have it).
  - Allowed values: `NONE`, `VIDEO_GEN`, `AUTO`
- `deliveryDestinations` (list of ExportDeliveryDestination, optional) — Destinations to deliver the finished export to when it completes, in addition to any delivery destinations already saved for the team. Each destination references a connected integration.

### ExportDeliveryDestination

- `integrationConnectionId` (string, required) — Id of the connected integration that will receive this export.
- `type` (enum, required) — Where to deliver the export within the connected integration.
  - Allowed values: `SLACK_CHANNEL`, `GOOGLE_DRIVE_FOLDER`
- `slackChannelId` (string, optional, nullable) — Target channel id. Required when `type` is `SLACK_CHANNEL`.
- `googleDriveFolderId` (string, optional, nullable) — Target folder id. Required when `type` is `GOOGLE_DRIVE_FOLDER`.

## Examples

**Request**

```json
{
  "prompt": "A golden retriever running through a sunlit meadow in slow motion, cinematic",
  "durationSeconds": 10,
  "quality": "HIGH",
  "autoExport": true
}
```

**Response**

```json
{
  "workflowRunId": "vg_work_ccm3abc123defcm3xyz789ghi",
  "projectId": "vg_proj_9dTk3mQ1rZ7xP4vN2sB6wc",
  "projectUrl": "https://app.videogen.io/project/1f0a2b3c-4d5e-6789-ab12-cdef34567890",
  "remixActionIds": []
}
```

**SDK Code**

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

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

const run = await client.workflows.promptToVideoClipAndWait({
  prompt: "A golden retriever running through a sunlit meadow in slow motion, cinematic",
  durationSeconds: 10,
  quality: "HIGH",
  autoExport: true,
});
console.log(run.downloadUrl);
```

```python
from videogen import VideoGen

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

run = client.workflows.prompt_to_video_clip_and_wait(
    prompt="A golden retriever running through a sunlit meadow in slow motion, cinematic",
    duration_seconds=10,
    quality="HIGH",
    auto_export=True,
)
print(run.download_url)
```