generate-video

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.