Seedance2 API

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:

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

Script mode prerequisites:

1. Verify XSKILL_API_KEY environment variable is set (run echo $XSKILL_API_KEY | head -c 10)
2. 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

3. 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:

1. Content – Who is the subject? What are they doing? Where?
2. Visuals – Lighting, color palette, texture, mood
3. Camera – Push in / pull out / pan / tilt / track / orbit / crane
4. Motion – Subject actions and pacing
5. 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

<details>
<summary><b>MCP Method</b></summary>

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)

</details>

<details>
<summary><b>Script Method</b></summary>

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}'

</details>

Image Editing (Modify Existing Images)

<details>
<summary><b>MCP Method</b></summary>

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

</details>

<details>
<summary><b>Script Method</b></summary>

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"}'

</details>

Poll Image Results

Images typically complete in 1–2 minutes.

<details>
<summary><b>MCP Method</b></summary>

Call get_task tool to check status:

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

</details>

<details>
<summary><b>Script Method</b></summary>

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

</details>

image_size Reference

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

<details>
<summary><b>MCP Method</b></summary>

Call upload_image tool: image_url or image_data

</details>

<details>
<summary><b>Script Method</b></summary>

# 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"

</details>

Submit Seedance 2.0 Task (Omni Reference Mode)

<details>
<summary><b>MCP Method</b></summary>

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)

</details>

<details>
<summary><b>Script Method</b></summary>

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"
  }'

</details>

Submit Seedance 2.0 Task (First & Last Frames Mode)

<details>
<summary><b>MCP Method</b></summary>

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

</details>

<details>
<summary><b>Script Method</b></summary>

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"
  }'

</details>