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

# AI video generation

Use `ai-video` commands for model-based video generation. For clip conversion,
merging, B-roll, and narrated content, see [video editing and production](/cli/video-editing-and-production).

## 1. Discover models and their inputs

```bash
simplified ai-video:models
simplified ai-video:models --model-id "MODEL_ID" --capability prompt
```

Choose an ID from the catalog, then inspect its supported duration, resolution,
aspect ratio, and required fields. Some models support audio generation or
reference-based modes; availability and accepted values are model-specific.

## 2. Generate a short clip

```bash
simplified ai-video:generate \
  --model "MODEL_ID" --capability prompt \
  --prompt "A slow camera move around a ceramic mug on a sunlit kitchen table." \
  --storage asset --wait
```

Add `--duration`, `--resolution`, or `--aspect-ratio` only after checking the
model's allowed values. Add `--generate-audio` when the chosen model supports it.
Generation can consume credits; review the model metadata before a large batch.

The storage choice controls where results are kept:

| `--storage` | Intended use                     |
| ----------- | -------------------------------- |
| `asset`     | A reusable workspace asset.      |
| `transient` | Temporary output.                |
| `default`   | The default gallery destination. |

## 3. Animate a reference

Upload the reference through [assets](/cli/assets-and-uploads) and wait until it
is ready. Inspect a model that supports `reference_image`, then use its UUID:

```bash
simplified ai-video:generate \
  --model "REFERENCE_MODEL_ID" --capability reference_image \
  --reference-images "ASSET_UUID" \
  --prompt "Subtle camera motion and natural light, preserving the product." \
  --storage asset --wait
```

Other models may support `multiple_images` or `first_last_frame`. Do not assume
one model supports every mode.

## 4. Supply model-specific parameters

Use `--parameters` for fields beyond the common flags. For a model whose
`first_last_frame` capability declares `first_frame_url` and `last_frame_url` as
file inputs:

```bash
simplified ai-video:generate \
  --model "FRAME_MODEL_ID" --capability first_last_frame \
  --prompt "A smooth transition between these two compositions." \
  --parameters '{"first_frame_url":"FIRST_ASSET_UUID","last_frame_url":"LAST_ASSET_UUID"}' \
  --storage asset --wait
```

File-typed fields take asset UUIDs even if their names end in `_url`. Use the
field types returned by discovery. Values in `--parameters` override matching
values supplied through the common flags.

## 5. Track the job

Without `--wait`, the response includes an `id` for the art and an
`art_variation_id` for the variation. Save both:

```bash
simplified ai-video:status --art-id "ART_ID" --id "ART_VARIATION_ID"
```

The status response uses `job_status`; `DONE` indicates completion and `FAILED`
indicates failure. The waiting mode polls every 30 seconds for up to 600 seconds.
On completion, it prints the output, which can include `file_url` and an asset ID.

If waiting times out, check that same job before resubmitting. Inspect the video,
then reuse it in a [social draft](/cli/social-publishing) or
[editing workflow](/cli/video-editing-and-production).