seedance2-api

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: seedance2-api
description: End-to-end AI video generation from storyboard concept to final output. Supports both MCP and standalone Python script modes; automatically detects availability and switches gracefully if MCP is unavailable. Generates reference images with Seedream 4.5 (text-to-image and image editing), then submits video tasks to Seedance 2.0 with configurable aspect ratios and durations.
license: MIT
---

# Seedance 2.0 Storyboard & Video Generation

End-to-end workflow from concept to final video: Storyboard → Reference images → Submit video task → Get results.

## Step 0: Determine Execution Mode (MCP or Script)

**Check MCP availability first:**

- Check `xskill-ai` MCP service status (read `mcps/user-xskill-ai/STATUS.md`)
- If MCP is available → use `submit_task` / `get_task` and other MCP tools
- If MCP is unavailable or returns errors → switch to Script Mode

**Script mode prerequisites:**

- Verify `XSKILL_API_KEY` environment variable is set (run `echo $XSKILL_API_KEY | head -c 10`)
- If not set, prompt the user:
  ```
  export XSKILL_API_KEY=sk-your-api-key
  ```
  Get your API Key: https://www.xskill.ai/#/v2/api-keys
- Verify `requests` is installed (`pip install requests`)

**Script path:** Located under this skill's directory at `scripts/seedance_api.py`:

```
# Find via Glob tool
glob: .cursor/skills/seedance2-api/scripts/seedance_api.py
```

In the following steps, each API call provides both MCP method and Script method. Choose one based on the Step 0 result.

## Step 1: Understand the User's Idea

Collect the following information (proactively ask if anything is missing):

- **Story concept**: one-sentence summary of the video
- **Duration**: 4–15 seconds
- **Aspect ratio**: 16:9 / 9:16 / 1:1 / 21:9 / 4:3 / 3:4
- **Visual style**: realistic / animation / ink wash / sci-fi / cyberpunk, etc.
- **Assets**: existing images/videos/audio, or need AI generation
- **Function mode**: first & last frame control (`first_last_frames`) or default omni mode (`omni_reference`)

## Step 2: Deep Dive (5 Dimensions)

Guide the user through each dimension for richer detail:

- **Content** – Who is the subject? What are they doing? Where?
- **Visuals** – Lighting, color palette, texture, mood
- **Camera** – Push in / pull out / pan / tilt / track / orbit / crane
- **Motion** – Subject actions and pacing
- **Audio** – Music style, sound effects, dialogue

## Step 3: Build Storyboard Structure

Break down shots along the timeline using this formula:

```
[Style] _____ style, _____ seconds, _____ ratio, _____ mood

0-Xs: [Camera movement] + [Visual content] + [Action description]
X-Ys: [Camera movement] + [Visual content] + [Action description]
...

[Audio] _____ music + _____ SFX + _____ dialogue
[References] @image_file_1 _____, @video_file_1 _____
```

See `reference.md` for detailed templates and examples.

## Step 4: Generate Reference Images (If Needed)

If the user has no existing assets, use Seedream 4.5 to generate character art, scenes, first/last frames, etc.

### Text-to-Image

Call `submit_task` tool:

- `model_id`: `fal-ai/bytedance/seedream/v4.5/text-to-image`
- `parameters`:
  - `prompt`: detailed image description (English works best)
  - `image_size`: choose based on video aspect ratio
  - `num_images`: number needed (1–6)

```bash
python .cursor/skills/seedance2-api/scripts/seedance_api.py submit \
  --model "fal-ai/bytedance/seedream/v4.5/text-to-image" \
  --params '{"prompt":"An astronaut in a white spacesuit...","image_size":"landscape_16_9","num_images":1}'
```

### Image Editing (Modify Existing Images)

Call `submit_task` tool:

- `model_id`: `fal-ai/bytedance/seedream/v4.5/edit`
- `parameters`:
  - `prompt`: editing instructions (use Figure 1/2/3 to reference images)
  - `image_urls`: array of input image URLs
  - `image_size`: output size

```bash
python .cursor/skills/seedance2-api/scripts/seedance_api.py submit \
  --model "fal-ai/bytedance/seedream/v4.5/edit" \
  --params '{"prompt