seedance 0.1.1

# 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](https://github.com/199-biotechnologies/agent-cli-framework).

## Install

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

## Auth

Get an API key at [console.byteplus.com/ark](https://console.byteplus.com/ark) and export it:

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

## Fast path

```bash
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

```bash
# 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