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

bash
${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.