seedance

Generate video with ByteDance Seedance 2.0 from the terminal. Agent-friendly CLI -- JSON envelope on pipe, human-readable on TTY, semantic exit codes, one binary, no MCP.

Built with the agent-cli-framework.

Install

cargo install --path .
# or (once published)
cargo install seedance

Auth

Get an API key at console.byteplus.com/ark and export it:

export SEEDANCE_API_KEY=sk-...
# ARK_API_KEY is also accepted

Fast path

seedance doctor
seedance generate --prompt "A cat yawns at the camera" --wait
# -> ~/Documents/seedance/<task-id>.mp4

Default output directory is ~/Documents/seedance/. Override with -o /path/to/file.mp4 or -o /some/dir/.

Reference inputs

Seedance 2.0 accepts a free mix of references in one content array:

Flag	Kind	Limit	Notes
--image / -i	Image	0-9	Path (base64'd inline) or URL. Role: reference_image
--first-frame	Image	1	Role: first_frame
--last-frame	Image	1	Role: last_frame (requires --first-frame)
--video / -v	Video	0-3	URL only (API restriction). Total <=15s
--audio / -a	Audio	0-3	wav/mp3. Path (base64'd) or URL. Total <=15s. Requires an image or video alongside.

Address references inside the prompt: [Image 1] the boy waves, [Video 1] camera style, [Audio 1] background music. Use time codes for multi-shot: [0-4s]: wide establishing shot; [4-8s]: push in.

Examples

# Text-to-video, wait and download
seedance generate \
  --prompt "A kitten yawns and blinks at the camera, cozy warm light" \
  --duration 6 --resolution 720p --ratio 16:9 \
  --wait --output kitten.mp4

# Multimodal reference-to-video with the fast tier
seedance generate \
  --prompt "[Image 1] the boy smiles; [Image 2] the corgi jumps in; [Video 1] camera motion" \
  --image boy.png --image corgi.png \
  --video https://my-cdn.example/style.mp4 \
  --fast --wait -o out.mp4

# Fire and forget, poll later
TASK=$(seedance gen --prompt "..." | jq -r '.data.id')
seedance status "$TASK"
seedance download "$TASK" -o final.mp4

Known quirks

• Audio upload mutates lyrics. Reported by @MrDavids1 + @simeonnz: uploading audio directly alters the song. Workaround: render a silent MP4 with the audio baked in, then pass it as --video. The API trusts reference videos for audio content but post-processes raw audio.
• No real human faces in references. ModelArk blocks direct upload of real human portraits. Use a face first generated by Seedance itself (those get a 30-day trust window per your key).
• Videos must be URLs, not local files. Host to S3/Cloudinary/etc. and pass the URL.

Commands

Command	Purpose
seedance generate / gen	Create a video generation task
seedance status <id> / get	Poll a task
seedance download <id>	Download the mp4 for a completed task
seedance cancel <id> / rm	Cancel a queued task
seedance models / ls	List available model ids
seedance doctor	Check API key, base URL, auth
seedance agent-info / info	Machine-readable capability manifest
seedance skill install	Deploy SKILL.md to Claude/Codex/Gemini
seedance config show / path	Show / locate config
seedance update [--check]	Self-update from GitHub Releases

Global flags: --json (force JSON), --quiet (suppress info), --help, --version.

Exit codes

Code	Meaning
0	Success
1	Transient (network, API, IO) -- retry
2	Config (missing API key, bad base URL) -- fix setup
3	Bad input -- fix arguments
4	Rate limited -- wait and retry

License

MIT