seedance2-api

Seedance 2.0 分镜与视频生成

从创意到最终视频的端到端工作流：分镜 → 参考图像 → 提交视频任务 → 获取结果。

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

先检查 MCP 是否可用：

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

脚本模式的前提条件：

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

  export XSKILL_API_KEY=sk-your-api-key
  

  获取 API Key：https://www.xskill.ai/#/v2/api-keys
• 验证是否已安装 requests（pip install requests）

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

# Find via Glob tool
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 个维度）

引导用户逐一完善以下维度，提供更丰富的细节：

• 内容 – 主体是谁？在做什么？在哪里？
• 视觉 – 光线、配色、纹理、氛围
• 摄影机 – 推近 / 拉远 / 摇摄 / 俯仰 / 跟拍 / 环绕 / 吊臂拍摄
• 动作 – 主体动作与节奏
• 音频 – 音乐风格、音效、对白

步骤 3：搭建分镜结构

使用以下公式按时间线拆分镜头：

[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 _____

详细模板和示例请参见 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":"An astronaut in a white spacesuit...","image_size":"landscape_16_9","num_images":1}'

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

调用 submit_task 工具：

• model_id：fal-ai/bytedance/seedream/v4.5/edit
• parameters：
  • prompt：编辑说明（使用 Figure 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":"Change the background to a forest","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 "TASK_ID_HERE"

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

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

image_size 参考

宽高比	推荐的 image_size	说明
16:9	landscape_16_9	横向
9:16	portrait_16_9	纵向
4:3	landscape_4_3	横向
3:4	portrait_4_3	纵向
1:1	square_hd	正方形
21:9	landscape_16_9	近似超宽屏

步骤 5：编写最终提示词

将分镜结构和参考图像整合到最终提示词中：

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

引用语法示例：

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

重要：image_files 中第 N 个 URL 对应 @image_file_N。video_files 和 audio_files 分别独立编号。

步骤 6：提交视频任务

处理素材 URL：

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

上传本地图像

调用 upload_image 工具：image_url 或 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"

提交 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 个，总时长 ≤ 15s）
  • 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": "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"
  }'

提交 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": "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"
  }'

步骤 7：轮询视频结果

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

轮询策略：

• 提交后，告知用户：“视频正在生成，预计约需 10 分钟”
• 60 秒后通过 get_task 首次查询
• 此后每隔 90 秒查询一次
• 每次查询后向用户报告状态

建议：自动轮询（在前台运行，间隔 30s，超时 600s）：

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

进度会输出到 stderr；完成后，最终 JSON 结果会输出到 stdout。

手动单次查询：

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

状态参考：

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

完整工作流示例

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

MCP 可用时

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

MCP 不可用时（脚本模式）

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

模型参数速查

Seedream 4.5 文生图

参数	类型	必填	描述
prompt	string	是	图像描述
image_size	string	否	auto_2K / auto_4K / square_hd / portrait_4_3 / portrait_16_9 / landscape_4_3 / landscape_16_9
num_images	int	否	1–6，默认值为 1

Seedream 4.5 图像编辑

参数	类型	必填	描述
prompt	string	是	编辑说明，将参考图像称为图 1/2/3
image_urls	array	是	输入图像 URL 列表
image_size	string	否	同上
num_images	int	否	1–6，默认值为 1

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

参数	类型	必填	描述
prompt	string	是	分镜提示词，使用 @image_file_N / @video_file_N / @audio_file_N
functionMode	string	否	omni_reference（默认值）
image_files	array	否	参考图像 URL 数组（最多 9 张）
video_files	array	否	参考视频 URL 数组（最多 3 个，总时长 ≤ 15s）
audio_files	array	否	参考音频 URL 数组（最多 3 个）
ratio	string	否	21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
duration	integer	否	4–15，默认值为 5
model	string	否	seedance_2.0_fast（默认值）/ seedance_2.0

Seedance 2.0 视频（首帧和尾帧模式）

参数	类型	必填	描述
prompt	string	是	视频描述提示词
functionMode	string	是	first_last_frames
filePaths	array	否	图片 URL 数组（0 = 文本生成视频，1 = 首帧，2 = 首帧和尾帧）
ratio	string	否	21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
duration	integer	否	4–15，默认值为 5
model	string	否	seedance_2.0_fast（默认） / seedance_2.0

工具速查

MCP 工具

操作	工具	关键参数
提交任务	submit_task	model_id、parameters
查询结果	get_task	task_id
上传图片	upload_image	image_url 或 image_data
检查余额	get_balance	（无）

脚本命令（MCP 不可用时）

操作	命令	描述
提交任务	python scripts/seedance_api.py submit --model MODEL --params '{...}'	返回 task_id
单次查询	python scripts/seedance_api.py query --task-id ID	返回当前状态
自动轮询	python scripts/seedance_api.py poll --task-id ID --interval N --timeout N	阻塞直到任务完成
检查余额	python scripts/seedance_api.py balance	返回账户余额
上传图片	python scripts/seedance_api.py upload --image-url URL or --image-path PATH	返回图片 URL

脚本路径说明： 上方的 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。