How do I install the Seedance2 API skill?

Run npx skillmds@latest add hexiaochun/seedance2-api in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Seedance2 API skill do?

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. It is listed under AI & ML on SkillMD.

Is Seedance2 API safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Seedance2 API?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Seedance2 API free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Seedance2 API?

hexiaochun (@hexiaochun) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Seedance2 API by hexiaochun — Agent Skill

Name: Seedance2 API
Rating: 4.2 (5 reviews)
Author: hexiaochun

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)

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

python .cursor/skills/seedance2-api/scripts/seedance_api.py submit \
  --model "fal-ai/bytedance/seedream/v4.5/edit" \
  --params '{"prompt":"Change the background to a forest","image_urls":["https://..."],"image_size":"landscape_16_9"}'

Poll Image Results

Images typically complete in 1–2 minutes.

Call get_task tool to check status:

First query after 30 seconds
Then every 30 seconds
Extract image URL when status is completed

Single query:

python .cursor/skills/seedance2-api/scripts/seedance_api.py query \
  --task-id "TASK_ID_HERE"

Auto-poll (recommended for images, interval 10s, timeout 180s):

python .cursor/skills/seedance2-api/scripts/seedance_api.py poll \
  --task-id "TASK_ID_HERE" --interval 10 --timeout 180

`image_size` Reference

Aspect Ratio	Recommended `image_size`	Note
16:9	`landscape_16_9`	Landscape
9:16	`portrait_16_9`	Portrait
4:3	`landscape_4_3`	Landscape
3:4	`portrait_4_3`	Portrait
1:1	`square_hd`	Square
21:9	`landscape_16_9`	Approximate ultrawide

Step 5: Compose the Final Prompt

Merge the storyboard structure and reference images into the final prompt:

Use @image_file_1, @image_file_2, etc. to reference images in the image_files array
Use @video_file_1, etc. to reference videos in the video_files array
Use @audio_file_1, etc. to reference audio in the audio_files array

Reference syntax example:

@image_file_1 as character reference, follow @video_file_1 camera movement, with @audio_file_1 as background music

Important: The Nth URL in image_files maps to @image_file_N. video_files and audio_files are independently numbered.

Step 6: Submit Video Task

Handle asset URLs:

Seedream-generated images: URL already available, use directly
User-provided web images: use directly
User-provided local images: upload first to get URL (see upload methods below)

Upload Local Images

Call upload_image tool: image_url or image_data

# Upload from URL
python .cursor/skills/seedance2-api/scripts/seedance_api.py upload \
  --image-url "https://example.com/image.png"

# Upload local file
python .cursor/skills/seedance2-api/scripts/seedance_api.py upload \
  --image-path "/path/to/local/image.png"

Submit Seedance 2.0 Task (Omni Reference Mode)

Call submit_task tool:

model_id: st-ai/super-seed2
parameters:
- prompt: the full prompt from Step 5
- functionMode: omni_reference (default, can be omitted)
- image_files: reference image URL array (up to 9, order matches @image_file_1/2/3...)
- video_files: reference video URL array (up to 3, total duration ≤ 15s)
- audio_files: reference audio URL array (up to 3)
- ratio: aspect ratio (16:9 / 9:16 / 1:1 / 21:9 / 4:3 / 3:4)
- duration: integer length (4–15)
- model: seedance_2.0_fast (default, faster) or seedance_2.0 (standard quality)

python .cursor/skills/seedance2-api/scripts/seedance_api.py submit \
  --model "st-ai/super-seed2" \
  --params '{
    "prompt": "Cinematic realistic sci-fi style, 15 seconds, 16:9...",
    "functionMode": "omni_reference",
    "image_files": ["https://img1.png", "https://img2.png"],
    "ratio": "16:9",
    "duration": 15,
    "model": "seedance_2.0_fast"
  }'

Submit Seedance 2.0 Task (First & Last Frames Mode)

Call submit_task tool:

model_id: st-ai/super-seed2
parameters:
- prompt: video description prompt
- functionMode: first_last_frames
- filePaths: image URL array (0 = text-to-video, 1 = first frame, 2 = first & last frames)
- ratio: aspect ratio
- duration: integer length
- model: seedance_2.0_fast or seedance_2.0

python .cursor/skills/seedance2-api/scripts/seedance_api.py submit \
  --model "st-ai/super-seed2" \
  --params '{
    "prompt": "Camera smoothly transitions from first frame to last frame, fluid motion",
    "functionMode": "first_last_frames",
    "filePaths": ["https://first-frame.png", "https://last-frame.png"],
    "ratio": "16:9",
    "duration": 5,
    "model": "seedance_2.0_fast"
  }'

Step 7: Poll for Video Results

Video generation takes approximately 10 minutes.

Polling strategy:

After submission, inform the user: "Video is generating, estimated ~10 minutes"
First query after 60 seconds via get_task
Then every 90 seconds
Report status to the user after each query

Recommended: auto-poll (runs in foreground, interval 30s, timeout 600s):

python .cursor/skills/seedance2-api/scripts/seedance_api.py poll \
  --task-id "TASK_ID_HERE" --interval 30 --timeout 600

Progress is printed to stderr; final JSON result is printed to stdout when complete.

Manual single query:

python .cursor/skills/seedance2-api/scripts/seedance_api.py query \
  --task-id "TASK_ID_HERE"

Status reference:

pending → "Queued..."
processing → "Generating..."
completed → Extract the video URL and present to the user
failed → Report the error; suggest adjusting the prompt and retrying

Full Workflow Example

User says: "Make a video of an astronaut walking on Mars"

When MCP Is Available

1. Gather info → 15s, 16:9, cinematic sci-fi style, no existing assets

2. Generate astronaut + Mars scene images with Seedream 4.5
   submit_task("fal-ai/bytedance/seedream/v4.5/text-to-image", {...})
   → poll get_task → get image URLs

3. Compose prompt → submit video task
   submit_task("st-ai/super-seed2", {...})

4. Poll get_task, ~10 min later → get video URL

When MCP Is Unavailable (Script Mode)

1. Gather info → 15s, 16:9, cinematic sci-fi style

2. Generate reference images:
   python scripts/seedance_api.py submit \
     --model "fal-ai/bytedance/seedream/v4.5/text-to-image" \
     --params '{"prompt":"An astronaut in white spacesuit on Mars...","image_size":"landscape_16_9"}'
   → get task_id

3. Poll for image results:
   python scripts/seedance_api.py poll --task-id "xxx" --interval 10 --timeout 180
   → get image URL

4. Submit video task:
   python scripts/seedance_api.py submit \
     --model "st-ai/super-seed2" \
     --params '{"prompt":"...storyboard prompt...","functionMode":"omni_reference","image_files":["IMAGE_URL"],"ratio":"16:9","duration":15,"model":"seedance_2.0_fast"}'
   → get task_id

5. Poll for video results:
   python scripts/seedance_api.py poll --task-id "xxx" --interval 30 --timeout 600
   → get video URL

Model Parameters Quick Reference

Seedream 4.5 Text-to-Image

Parameter	Type	Required	Description
`prompt`	string	Yes	Image description
`image_size`	string	No	`auto_2K` / `auto_4K` / `square_hd` / `portrait_4_3` / `portrait_16_9` / `landscape_4_3` / `landscape_16_9`
`num_images`	int	No	1–6, default 1

Seedream 4.5 Image Editing

Parameter	Type	Required	Description
`prompt`	string	Yes	Editing instructions, reference images as Figure 1/2/3
`image_urls`	array	Yes	Input image URL list
`image_size`	string	No	Same as above
`num_images`	int	No	1–6, default 1

Seedance 2.0 Video (Omni Reference Mode)

Parameter	Type	Required	Description
`prompt`	string	Yes	Storyboard prompt, use `@image_file_N` / `@video_file_N` / `@audio_file_N`
`functionMode`	string	No	`omni_reference` (default)
`image_files`	array	No	Reference image URL array (up to 9)
`video_files`	array	No	Reference video URL array (up to 3, total ≤ 15s)
`audio_files`	array	No	Reference audio URL array (up to 3)
`ratio`	string	No	`21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`
`duration`	integer	No	4–15, default 5
`model`	string	No	`seedance_2.0_fast` (default) / `seedance_2.0`

Seedance 2.0 Video (First & Last Frames Mode)

Parameter	Type	Required	Description
`prompt`	string	Yes	Video description prompt
`functionMode`	string	Yes	`first_last_frames`
`filePaths`	array	No	Image URL array (0 = text-to-video, 1 = first frame, 2 = first & last)
`ratio`	string	No	`21:9` / `16:9` / `4:3` / `1:1` / `3:4` / `9:16`
`duration`	integer	No	4–15, default 5
`model`	string	No	`seedance_2.0_fast` (default) / `seedance_2.0`

Tools Quick Reference

MCP Tools

Action	Tool	Key Parameters
Submit task	`submit_task`	`model_id`, `parameters`
Query result	`get_task`	`task_id`
Upload image	`upload_image`	`image_url` or `image_data`
Check balance	`get_balance`	(none)

Script Commands (When MCP Is Unavailable)

Action	Command	Description
Submit task	`python scripts/seedance_api.py submit --model MODEL --params '{...}'`	Returns `task_id`
Single query	`python scripts/seedance_api.py query --task-id ID`	Returns current status
Auto-poll	`python scripts/seedance_api.py poll --task-id ID --interval N --timeout N`	Blocks until done
Check balance	`python scripts/seedance_api.py balance`	Returns account balance
Upload image	`python scripts/seedance_api.py upload --image-url URL or --image-path PATH`	Returns image URL

Script path note: The scripts/seedance_api.py path above is relative to .cursor/skills/seedance2-api/. Use the full path .cursor/skills/seedance2-api/scripts/seedance_api.py when executing, or cd into the skill directory first.

Seedance 2.0 Limitations

Realistic human face uploads are not supported
Maximum 12 files: images ≤ 9 + videos ≤ 3 + audio ≤ 3
Total video/audio reference duration ≤ 15 seconds
Video references consume more credits

More Resources

See reference.md for detailed storyboard templates, full examples, and camera movement glossary.

Seedance2 API

File contents

Seedance 2.0 Storyboard & Video Generation

Step 0: Determine Execution Mode (MCP or Script)

Step 1: Understand the User's Idea

Step 2: Deep Dive (5 Dimensions)

Step 3: Build Storyboard Structure

Step 4: Generate Reference Images (If Needed)

Text-to-Image

Image Editing (Modify Existing Images)

Poll Image Results

`image_size` Reference

Step 5: Compose the Final Prompt

Step 6: Submit Video Task

Upload Local Images

Submit Seedance 2.0 Task (Omni Reference Mode)

Submit Seedance 2.0 Task (First & Last Frames Mode)

Step 7: Poll for Video Results

Full Workflow Example

When MCP Is Available

When MCP Is Unavailable (Script Mode)

Model Parameters Quick Reference

Seedream 4.5 Text-to-Image

Seedream 4.5 Image Editing

Seedance 2.0 Video (Omni Reference Mode)

Seedance 2.0 Video (First & Last Frames Mode)

Tools Quick Reference

MCP Tools

Script Commands (When MCP Is Unavailable)

Seedance 2.0 Limitations

More Resources

Frequently asked questions

Seedance2 API

File contents

Seedance 2.0 Storyboard & Video Generation

Step 0: Determine Execution Mode (MCP or Script)

Step 1: Understand the User's Idea

Step 2: Deep Dive (5 Dimensions)

Step 3: Build Storyboard Structure

Step 4: Generate Reference Images (If Needed)

Text-to-Image

Image Editing (Modify Existing Images)

Poll Image Results

image_size Reference

Step 5: Compose the Final Prompt

Step 6: Submit Video Task

Upload Local Images

Submit Seedance 2.0 Task (Omni Reference Mode)

Submit Seedance 2.0 Task (First & Last Frames Mode)

Step 7: Poll for Video Results

Full Workflow Example

When MCP Is Available

When MCP Is Unavailable (Script Mode)

Model Parameters Quick Reference

Seedream 4.5 Text-to-Image

Seedream 4.5 Image Editing

Seedance 2.0 Video (Omni Reference Mode)

Seedance 2.0 Video (First & Last Frames Mode)

Tools Quick Reference

MCP Tools

Script Commands (When MCP Is Unavailable)

Seedance 2.0 Limitations

More Resources

Related skills

Frequently asked questions

How do I install the Seedance2 API skill?

What does the Seedance2 API skill do?

Is Seedance2 API safe to use?

Which AI agents work with Seedance2 API?

Is Seedance2 API free to use?

Who published Seedance2 API?

`image_size` Reference