> ## Documentation Index
> Fetch the complete documentation index at: https://wholly.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate AI Video

> Generate short AI videos from text prompts or reference images.

Create dynamic AI-generated videos from text prompts or image references.

## Create a Video Generation Task

```http theme={null}
POST /api/v1/runway/generate
```

## Authentication

All API requests require a Bearer Token.

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Usage Guide

* Create short AI videos of 5–10 seconds.
* Generate videos from text descriptions or reference images.
* Suitable for social media content, digital art, and concept visualization.

## Parameters

## Prompt

<ParamField body="prompt" type="string" required>
  Use `prompt` to be specific about the **subject, action, style, and setting**. With an image, describe how to animate or modify the image..

  **Maximum length:** `1,800` characters.
</ParamField>

## Image Reference

<ParamField body="imageUrl" type="string">
  `imageUrl` is optional. When supplied, the AI creates a video by animating or extending the referenced image.

  When `imageUrl` is provided, `aspectRatio` is invalid and the final aspect ratio is determined by the image.
</ParamField>

## Duration

<ParamField body="duration" type="number" required>
  Generated video duration in seconds.

  Supported values:

  * `5`
  * `10`

  **Note:** 10-second videos do not support 1080p resolution. <br /> **Default:** `5`
</ParamField>

## Quality

<ParamField body="quality" type="string" required>
  Specify the resolution of the output video.

  Supported output resolutions:

  * `720p`
  * `1080p`

  **Note:** 10-second videos do not support 1080p resolution. <br /> **Default:** `720p`
</ParamField>

## Aspect Ratio

<ParamField body="aspectRatio" type="string">
  Applies to multi-image generation. In single-image mode, video dimensions follow the source image dimensions.

  Supported values: `3:4`, `4:3`, `1:1`, `16:9`, `9:16`.

  For text-only generation, `aspectRatio` must be explicitly specified.
</ParamField>

## Watermark

<ParamField body="waterMark" type="string">
  Use `waterMark` controls watermark text in the bottom-right corner.

  * Empty string: no watermark.
  * Non-empty string: displays the specified text.

  Example: `whollyapi.com`
</ParamField>

## Request Example

```json theme={null}
{
  "prompt": "A fluffy orange cat dancing energetically in a colorful room with disco lights",
  "imageUrl": "https://example.com/cat-image.jpg",
  "duration": 5,
  "quality": "720p",
  "aspectRatio": "9:16",
  "waterMark": "kie.ai",
}
```

## Text-to-Video Example

```json theme={null}
{
  "prompt": "A fluffy orange cat dancing energetically in a colorful room with disco lights",
  "duration": 5,
  "quality": "720p",
  "aspectRatio": "9:16",
  "waterMark": "",
}
```

## Image-to-Video Example

```json theme={null}
{
  "prompt": "Animate the cat dancing energetically while the disco lights flicker around it.",
  "imageUrl": "https://example.com/cat-image.jpg",
  "duration": 5,
  "quality": "720p",
  "waterMark": "kie.ai",
}
```

## Create Task Response

<ResponseField name="code" type="number">
  Response status code.
</ResponseField>

<ResponseField name="msg" type="string">
  Response message. Contains the error description when the request fails.

  **Example:** `success`
</ResponseField>

<ResponseField name="data" type="object" required>
  The task data object containing task id.

  <ResponseField name="taskId" type="string" required>
    The unique identifier for this task.

    **Example:** `ee603959-98c4-debb-bgfgbfg45`
  </ResponseField>
</ResponseField>

## Query Task Status

After submitting a task, use the unified query endpoint to check the task progress and retrieve the generated results.

<Card title="Get Task Details" icon="search" href="/get-ai-video-details">
  Check task status, monitor generation progress, and retrieve results.
</Card>

## Error Response

```json theme={null}
{
  "code": 500,
  "msg": "Server Error - An unexpected error occurred while processing the request",
  "data": null
}
```

## Developer Notes

* Generated videos are stored for **14 days** before automatic deletion.
* Text-only generation requires `aspectRatio`.
* With `imageUrl`, the image determines the final aspect ratio.
* 10-second videos cannot be generated at 1080p.

## Response Status Codes

|  Code | Meaning                                                                                  |
| ----: | ---------------------------------------------------------------------------------------- |
| `200` | Success — request processed successfully.                                                |
| `401` | Unauthorized — authentication credentials are missing or invalid.                        |
| `404` | Not Found — requested resource or endpoint does not exist.                               |
| `422` | Validation Error — request parameters failed validation.                                 |
| `451` | Failed to fetch the image; verify access limits imposed by the user or service provider. |
| `455` | Service Unavailable — system is undergoing maintenance.                                  |
| `500` | Server Error — unexpected error while processing the request.                            |

The source also documents these broader error codes:

|  Code | Meaning                                                         |
| ----: | --------------------------------------------------------------- |
| `402` | Insufficient Credits.                                           |
| `408` | Upstream service issue; no result returned for over 10 minutes. |
| `429` | Rate Limited.                                                   |
| `501` | Generation Failed.                                              |
| `505` | Feature Disabled.                                               |