Seedance 2.0 故事板与视频生成

从概念到最终视频的端到端工作流：故事板 → 参考图像 → 提交视频任务 → 获取结果。

步骤 0：确定执行模式（MCP 或脚本）

首先检查 MCP 可用性：

1. 检查 xskill-ai MCP 服务状态（读取 mcps/user-xskill-ai/STATUS.md）
2. 如果 MCP 可用 → 使用 submit_task / get_task 和其他 MCP 工具
3. 如果 MCP 不可用或返回错误 → 切换到脚本模式

脚本模式前提条件：

1. 验证 XSKILL_API_KEY 环境变量是否已设置（运行 echo $XSKILL_API_KEY | head -c 10）
2. 如果未设置，提示用户：

   export XSKILL_API_KEY=sk-您的-api-密钥
   获取您的 API 密钥：https://www.xskill.ai/#/v2/api-keys
   

3. 验证 requests 是否已安装（pip install requests）

脚本路径： 位于此技能目录下的 scripts/seedance_api.py：

# 通过 Glob 工具查找
glob: .cursor/skills/seedance2-api/scripts/seedance_api.py

在以下步骤中，每个 API 调用都提供了MCP 方法和脚本方法。根据步骤 0 的结果选择其一。

步骤 1：理解用户的想法

收集以下信息（如果缺失任何信息，请主动询问）：

• 故事概念：一句话概括视频内容
• 时长：4–15 秒
• 宽高比：16:9 / 9:16 / 1:1 / 21:9 / 4:3 / 3:4
• 视觉风格：写实 / 动画 / 水墨 / 科幻 / 赛博朋克等
• 素材：现有图像/视频/音频，或需要 AI 生成
• 功能模式：首尾帧控制（first_last_frames）或默认全能参考模式（omni_reference）

步骤 2：深入挖掘（5 个维度）

引导用户从每个维度思考，以获得更丰富的细节：

1. 内容 – 主角是谁？他们在做什么？在哪里？
2. 视觉 – 光线、调色板、质感、氛围
3. 镜头 – 推 / 拉 / 摇 / 移 / 跟 / 环绕 / 升降
4. 运动 – 主体动作和节奏
5. 音频 – 音乐风格、音效、对话

步骤 3：构建故事板结构

使用以下公式沿时间线分解镜头：

[风格] _____ 风格， _____ 秒， _____ 比例， _____ 氛围

0-X秒：[镜头运动] + [视觉内容] + [动作描述]
X-Y秒：[镜头运动] + [视觉内容] + [动作描述]
...

[音频] _____ 音乐 + _____ 音效 + _____ 对话
[参考] @image_file_1 _____, @video_file_1 _____

有关详细的模板和示例，请参阅 reference.md。

步骤 4：生成参考图像（如果需要）

如果用户没有现有素材，请使用 Seedream 4.5 生成角色艺术、场景、首尾帧等。

文生图

调用 submit_task 工具：

• model_id：fal-ai/bytedance/seedream/v4.5/text-to-image
• parameters：
  • prompt：详细的图像描述（英文效果最佳）
  • image_size：根据视频宽高比选择
  • num_images：所需图像数量（1–6）

python .cursor/skills/seedance2-api/scripts/seedance_api.py submit \
  --model "fal-ai/bytedance/seedream/v4.5/text-to-image" \
  --params '{"prompt":"一个穿着白色宇航服的宇航员...","image_size":"landscape_16_9","num_images":1}'

图像编辑（修改现有图像）

调用 submit_task 工具：

• model_id：fal-ai/bytedance/seedream/v4.5/edit
• parameters：
  • prompt：编辑说明（使用图 1/2/3 来指代图像）
  • image_urls：输入图像 URL 数组
  • image_size：输出尺寸

python .cursor/skills/seedance2-api/scripts/seedance_api.py submit \
  --model "fal-ai/bytedance/seedream/v4.5/edit" \
  --params '{"prompt":"将背景改为森林","image_urls":["https://..."],"image_size":"landscape_16_9"}'

轮询图像结果

图像通常需要 1–2 分钟完成。

调用 get_task 工具检查状态：

• 首次查询在 30 秒后
• 然后每 30 秒查询一次
• 当状态为 completed 时提取图像 URL

单次查询：

python .cursor/skills/seedance2-api/scripts/seedance_api.py query \
  --task-id "此处填写任务ID"

自动轮询（推荐用于图像，间隔 10 秒，超时 180 秒）：

python .cursor/skills/seedance2-api/scripts/seedance_api.py poll \
  --task-id "此处填写任务ID" --interval 10 --timeout 180

image_size 参考

步骤 5：撰写最终提示词

将故事板结构和参考图像合并到最终提示词中：

• 使用 @image_file_1、@image_file_2 等在 image_files 数组中引用图像
• 使用 @video_file_1 等在 video_files 数组中引用视频
• 使用 @audio_file_1 等在 audio_files 数组中引用音频

引用语法示例：

@image_file_1 作为角色参考，跟随 @video_file_1 的镜头运动，使用 @audio_file_1 作为背景音乐

重要提示： image_files 中的第 N 个 URL 映射到 @image_file_N。video_files 和 audio_files 是独立编号的。

步骤 6：提交视频任务

处理素材 URL：

• Seedream 生成的图像：URL 已可用，直接使用
• 用户提供的网络图像：直接使用
• 用户提供的本地图像：先上传以获取 URL（请参阅下面的上传方法）

上传本地图像

调用 upload_image 工具：image_url 或 image_data

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

# 上传本地文件
python .cursor/skills/seedance2-api/scripts/seedance_api.py upload \
  --image-path "/本地图像路径/image.png"

提交 Seedance 2.0 任务（全能参考模式）

调用 submit_task 工具：

• model_id：st-ai/super-seed2
• parameters：
  • prompt：步骤 5 中的完整提示词
  • functionMode：omni_reference（默认，可省略）
  • image_files：参考图像 URL 数组（最多 9 个，顺序与 @image_file_1/2/3… 匹配）
  • video_files：参考视频 URL 数组（最多 3 个，总时长 ≤ 15 秒）
  • audio_files：参考音频 URL 数组（最多 3 个）
  • ratio：宽高比（16:9 / 9:16 / 1:1 / 21:9 / 4:3 / 3:4）
  • duration：整数时长（4–15）
  • model：seedance_2.0_fast（默认，更快）或 seedance_2.0（标准画质）

python .cursor/skills/seedance2-api/scripts/seedance_api.py submit \
  --model "st-ai/super-seed2" \
  --params '{
    "prompt": "电影感写实科幻风格，15秒，16:9...",
    "functionMode": "omni_reference",
    "image_files": ["https://img1.png", "https://img2.png"],
    "ratio": "16:9",
    "duration": 15,
    "model": "seedance_2.0_fast"
  }'

提交 Seedance 2.0 任务（首尾帧模式）

调用 submit_task 工具：

• model_id：st-ai/super-seed2
• parameters：
  • prompt：视频描述提示词
  • functionMode：first_last_frames
  • filePaths：图像 URL 数组（0 = 文生视频，1 = 首帧，2 = 首尾帧）
  • ratio：宽高比
  • duration：整数时长
  • model：seedance_2.0_fast 或 seedance_2.0

python .cursor/skills/seedance2-api/scripts/seedance_api.py submit \
  --model "st-ai/super-seed2" \
  --params '{
    "prompt": "镜头从首帧平滑过渡到尾帧，流畅运动",
    "functionMode": "first_last_frames",
    "filePaths": ["https://首帧.png", "https://尾帧.png"],
    "ratio": "16:9",
    "duration": 5,
    "model": "seedance_2.0_fast"
  }'

步骤 7：轮询视频结果

视频生成大约需要 10 分钟。

轮询策略：

1. 提交后，告知用户：“视频正在生成，预计约 10 分钟”
2. 首次查询在 60 秒后，通过 get_task
3. 然后每 90 秒查询一次
4. 每次查询后向用户报告状态

推荐：自动轮询（在前台运行，间隔 30 秒，超时 600 秒）：

python .cursor/skills/seedance2-api/scripts/seedance_api.py poll \
  --task-id "此处填写任务ID" --interval 30 --timeout 600

进度会打印到 stderr；完成后最终的 JSON 结果会打印到 stdout。

手动单次查询：

python .cursor/skills/seedance2-api/scripts/seedance_api.py query \
  --task-id "此处填写任务ID"

状态参考：

• pending → “已排队…”
• processing → “生成中…”
• completed → 提取视频 URL 并呈现给用户
• failed → 报告错误；建议调整提示词后重试

完整工作流示例

用户说：“制作一个宇航员在火星上行走的视频”

当 MCP 可用时

1. 收集信息 → 15秒，16:9，电影感科幻风格，无现有素材

2. 使用 Seedream 4.5 生成宇航员 + 火星场景图像
   submit_task(“fal-ai/bytedance/seedream/v4.5/text-to-image”， {...})
   → 轮询 get_task → 获取图像 URL

3. 撰写提示词 → 提交视频任务
   submit_task(“st-ai/super-seed2”， {...})

4. 轮询 get_task，约 10 分钟后 → 获取视频 URL

当 MCP 不可用时（脚本模式）

1. 收集信息 → 15秒，16:9，电影感科幻风格

2. 生成参考图像：
   python scripts/seedance_api.py submit \
     --model “fal-ai/bytedance/seedream/v4.5/text-to-image” \
     --params ‘{“prompt”：“一个穿着白色宇航服的宇航员在火星上...”，“image_size”：“landscape_16_9”}’
   → 获取 task_id

3. 轮询图像结果：
   python scripts/seedance_api.py poll --task-id “xxx” --interval 10 --timeout 180
   → 获取图像 URL

4. 提交视频任务：
   python scripts/seedance_api.py submit \
     --model “st-ai/super-seed2” \
     --params ‘{“prompt”：“...故事板提示词...”，“functionMode”：“omni_reference”，“image_files”:[“图像URL”]，“ratio”:“16:9”，“duration”:15，“model”:“seedance_2.0_fast”}’
   → 获取 task_id

5. 轮询视频结果：
   python scripts/seedance_api.py poll --task-id “xxx” --interval 30 --timeout 600
   → 获取视频 URL

模型参数快速参考

Seedream 4.5 文生图

Seedream 4.5 图像编辑

Seedance 2.0 视频（全能参考模式）

Seedance 2.0 视频（首尾帧模式）

工具快速参考

MCP 工具

脚本命令（当 MCP 不可用时）

脚本路径说明： 上面的 scripts/seedance_api.py 路径是相对于 .cursor/skills/seedance2-api/ 的。执行时请使用完整路径 .cursor/skills/seedance2-api/scripts/seedance_api.py，或先 cd 进入技能目录。

Seedance 2.0 限制

• 不支持上传真实人像面孔
• 最多 12 个文件：图像 ≤ 9 + 视频 ≤ 3 + 音频 ≤ 3
• 视频/音频参考总时长 ≤ 15 秒
• 视频参考消耗更多积分

更多资源

有关详细的故事板模板、完整示例和镜头运动术语表，请参阅 reference.md。