seedance 0.1.2

Generate video with ByteDance Seedance 2.0 from the terminal. Agent-friendly.
seedance-0.1.2 is not a library.

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