/generate-video

name: generate-video
description: Generate short videos from a text prompt or from still images using ByteDance Seedance on Volcengine Ark. Use this skill whenever the user wants to create, generate, render, or animate a video, clip, animation, motion graphic, or product demo — including text-to-video ("a drone shot over a forest at sunrise") and image-to-video, where a still becomes the first frame, or two stills are morphed start-to-end. Prefer this skill over describing a video in text.
user-invocable: true
argument-hint: "\"PROMPT\" [-o out.mp4] [--first-frame img] [--last-frame img] [--duration 5] [--resolution 720p] [--ratio 16:9] [--no-audio] [--seed N]"
allowed-tools: ["Read", "Write", "AskUserQuestion", "Bash(uv run:*)", "Bash(*/generate_video.py:*)"]

Generate Video (Seedance on Volcengine Ark)

Turn a text prompt — optionally anchored by a first frame, a last frame, or reference images — into a short video. The script submits an async task, polls until it finishes, and downloads the `.mp4`. Generation takes a few minutes, so set expectations and let it run.

Prerequisites

• `uv` available (self-contained `uv run` script; deps install on first run).
• A Volcengine Ark key. Resolved progressively, so any one works:
• `export ARK_API_KEY=...` in the shell, or
• a `.env` file (checked in order: `$PWD/.env`, then `${CLAUDE_PLUGIN_ROOT}/.env`), or
• `--api-key ...` on the command line.

**CRITICAL** -- Never paste the API key into chat or commit a `.env`. If the key is missing, the script prints exactly how to set it — relay that instead of guessing.

Workflow

1. Decide the mode

• **Text-to-video** — prompt only. Best when there is no source image.
• **Image-to-video** — pass `--first-frame img.png`. The still becomes the opening frame and

the model adds motion. This is the right mode for animating a storyboard panel or product render.

• **First→last morph** — pass both `--first-frame a.png` and `--last-frame b.png` to interpolate

a transition between two stills.

• **Reference-guided** — `--image path:reference_image` (repeatable) to steer style/composition.

If the user attached an image, default to image-to-video unless they clearly want a fresh scene.

2. Craft the prompt

Read `references/prompting.md` before writing a non-trivial prompt. Seedance responds well to prompts that describe the shot over time (beats like `[0s-2s] … [2s-5s] …`), the camera move, and what must stay fixed. For image-to-video, explicitly state which traits of the source to preserve (style, framing, colors) so the clip does not drift.

3. Run the script

Invoke it directly (the shebang runs it through `uv`):

${CLAUDE_PLUGIN_ROOT}/skills/generate-video/scripts/generate_video.py "PROMPT" -o OUT.mp4 [flags]

Flags:

| Flag | Purpose | Default | |------|---------|---------| | `-o, --output` | Output `.mp4` path | `output.mp4` | | `--first-frame` | Start-frame image (image-to-video) | none | | `--last-frame` | End-frame image (morph start→end) | none | | `--image` | `PATH` or `PATH:ROLE` (`first_frame`/`last_frame`/`reference_image`); repeatable | none | | `--ratio` | Aspect ratio: `16:9`, `9:16`, `1:1`, … | `16:9` | | `--resolution` | `480p` / `720p` / `1080p` (no 2K/4K on Ark) | `720p` | | `--duration` | seconds, `4`–`15` for Seedance 2.0 | 5 | | `--watermark` | Keep the provider watermark | off | | `--no-audio` | Disable native audio (2.0 generates synced audio by default) | audio on | | `--seed` | Integer seed for reproducibility | random | | `--model` | `pro`, `fast`, `mini`, or a raw id (else `SEEDANCE_MODEL`) | `pro` |

**Models** (pass the alias to `--model` or set `SEEDANCE_MODEL`):

| Alias | Model id | Use for | |-------|----------|---------| | `pro` (default) | `doubao-seedance-2-0-260128` | full quality, up to 1080p | | `fast` | `doubao-seedance-2-0-fast-260128` | cheaper / faster, 720p max | | `mini` | `doubao-seedance-2-0-mini-260615` | lightest / cheapest |

The script blocks while polling (status prints to stderr). For batch work, prefer longer single runs over many tiny ones — each task has fixed overhead, and the API bills per task.

4. Report

Tell the user the saved path and the settings used (duration, resolution). The output is an `.mp4`: reference it by path. If a task fails, relay the provider's error message and suggest a fix (often a softer prompt, a different ratio, or a valid source image).

Configuration is progressive (the key best practice)

API key, model id, AND base URL are each resolved by `lib/progressive_env.py` in this order, stopping at the first hit: **CLI flag → process env → `.env` chain → built-in default**.

Two consequences worth knowing:

• **Switch model versions without code changes.** The default is the current

`doubao-seedance-2-0-260128`; to use a different/newer Seedance build, set `export SEEDANCE_MODEL=<id>` (or pass `--model`). Confirm the exact id in the Ark console — do not assume a marketing name like "Seedance 3" maps to a literal model id.

• **Switch regions without code changes.** Default base URL is the cn-beijing endpoint; set

`export ARK_BASE_URL=...` for another Ark region.

Files

• `scripts/generate_video.py` — the generator (Seedance via Ark REST, async + poll + download).
• `references/prompting.md` — prompt-writing guide and full parameter reference.
• `${CLAUDE_PLUGIN_ROOT}/lib/progressive_env.py` — shared progressive config resolver.