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

# Video generation

> Choose a mode, provide media inputs, and handle asynchronous task results.

Video generation is asynchronous. First create a task, then retrieve it until it reaches a terminal state.

## Request structure

```json theme={"dark"}
{
  "model": "dreamina-seedance-2-0-260128",
  "mode": "image_first_frame",
  "prompt": "The product slowly rotates on a clean studio turntable.",
  "contentPreFilter": true,
  "assets": {
    "firstFrameImage": "https://example.com/product.jpg"
  },
  "controls": {
    "duration": 5,
    "resolution": "720p",
    "ratio": "adaptive",
    "generateAudio": false
  },
  "providerOptions": {}
}
```

## Generation modes

| Mode                     | Required input              | Typical use                     |
| ------------------------ | --------------------------- | ------------------------------- |
| `text_to_video`          | `prompt`                    | Generate a new video from text  |
| `image_first_frame`      | `assets.firstFrameImage`    | Animate a starting image        |
| `image_first_last_frame` | First and last frame images | Control both ends of a shot     |
| `multimodal_reference`   | Reference image or video    | Guide subject, style, or motion |
| `video_modify`           | `assets.sourceVideo`        | Modify an existing video        |
| `video_extend`           | `assets.sourceVideo`        | Extend an existing video        |

If `mode` is omitted, GENGEN can infer it from the supplied assets. Set it explicitly when you want predictable validation.

## Media inputs

`assets` accepts HTTPS URLs and owned `asset://` references where supported.

* `firstFrameImage` and `lastFrameImage` control boundary frames.
* `referenceImages` accepts up to 9 image references for supported Seedance modes.
* `referenceVideos` accepts up to 3 video references per upstream request.
* `referenceAudio` adds audio guidance and cannot be the only multimodal input.
* `sourceVideo` is used by video modification and extension.

<Tip>
  Use GENGEN asset references for files already registered in the same workspace. Requests cannot use private assets owned by another workspace.
</Tip>

## Output controls

Common controls include:

* `duration`: model-dependent output duration in seconds; supported Seedance models also accept `-1` for model-selected duration.
* `resolution`: `480p`, `720p`, `1080p`, or `4k`, subject to model support.
* `ratio`: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, or `adaptive`.
* `generateAudio`: request synchronized audio when supported.
* `watermark`: add a provider watermark.
* `returnLastFrame`: return a last-frame image when supported.
* `serviceTier`: `default` or `flex`, subject to model support.

## Task lifecycle

```mermaid theme={"dark"}
flowchart LR
  A["Create task"] --> B["pending or queued"]
  B --> C["running"]
  C --> D["succeeded"]
  C --> E["failed"]
  B --> F["cancelled"]
```

Poll the retrieve endpoint at a reasonable interval. Treat `succeeded`, `failed`, `cancelled`, and `expired` as terminal. Some provider compatibility responses can also use `completed`; GENGEN normalizes new responses where possible.

<Warning>
  Creating a task reserves wallet balance. Retrieving a successful terminal result can finalize the corresponding charge. Deleting or cancelling a task changes remote and local task state.
</Warning>

## Compatibility

Older integrations may still send provider-native `content[]` bodies or snake\_case fields. They remain compatibility inputs, but new integrations should use `assets`, `controls`, and `providerOptions`.