zcbot/skills/videogen/SKILL.md

name	description
videogen	用豆包 Seedance 2.0 Fast 生视频(`seedance` tool)。**任何生视频任务调 tool 前必须 load 本 skill**。触发词:视频 / 动画 / 动起来 / 做个 video / 做段视频 / 出段视频 / 生成视频 / mov / mp4 / 短片 / 镜头 / 运动镜头 / 演示视频 / 动效。核心:视频比图贵 10 倍(¥1.86-¥4+ / 段),且要等 Fast 30-90s / Pro 2-3min,问清楚再画 + 强制确认。

Videogen

把"我想要个视频"变成一段能用的视频。流程:

诊断模糊度(6 维) → 一次性给推断 + 待确认项 → 用户拍板维度 → 装配最终 prompt + 参数 → ⛔ 把 prompt+参数完整贴给用户看 + 问改不改 → 用户明确确认后 → 调 seedance

每次 seedance 调用 ¥1.86 起(480p 4s)→ ¥4.00 起(720p 5s)→ ¥12+(720p 15s),且要等 30-90 秒才出片。贵 + 慢 = 试错代价高,必须问清楚再调。

⛔ 调 tool 前的强制门(铁律,比 imagegen 更严格)

任何情况下,在 seedance tool call 发出去之前,都必须先把最终装配好的 prompt(包括 resolution / ratio / duration / watermark 参数)用对话消息明文展示给用户,然后问"这样画?要改什么?"并 ⛔ BLOCKING 等用户明确回复。

• 用户回复 "可以" / "OK" / "就这样" / "对" / "嗯" / "画吧" / "出片吧" / 简单确认 → 可以调 tool
• 用户回复 "把 X 改成 Y" / "时长改 8s" / "镜头换成 Y" → 改完后再次贴最终 prompt + 再次等确认
• 用户沉默 / 长时间不回 / 追问别的事 → 不算确认,继续等,不要自作主张
• 用户回 "看起来不错" / "差不多" / 模棱两可 → 主动追问一句"这就开烧 ¥X?",拿到明确"是"再调

为什么比 imagegen 还严:视频单价 ¥4 起,比图贵 10 倍以上;一次失败相当于 18 张错图;且要等 Fast 30-90s / Pro 2-3min,用户改方向的等待代价也很高。装配 prompt 不等于授权调用 —— 装配是模型脑内运算,授权要落到用户的"嗯,画吧"上。

何时用本 skill

• 用户明确说"做个视频" / "出段视频" / "动画" / "动起来" / "镜头扫过" / "演示视频"
• 用户原本要 ppt / 海报 / 申报书,主动问能不能配段视频(此时介绍价格 + 时长引导决策)
• 用户拿到 seedream 生的静态图后说"想动起来" / "加点运动" — 注意 phase 1 只支持 t2v 文生视频,不支持从已有图生视频(i2v),要告诉用户这点

何时不走本 skill

• 用户没主动要视频(别为"丰富回复"装饰性生视频 —— 比图更严重的浪费红线)
• 用户要的是流程/结构动效(节点-箭头-步骤逐次出现)→ 这是 ppt 动画 / mermaid + ppt 转场的事,不是视频
• 用户要的是实拍素材 / 已有视频剪辑 → seedance 是 AI 生成,不是素材库;告诉用户走 unsplash / pexels 等
• 用户有具体参考视频说"按这个改" → phase 1 不支持 i2v / v2v,告诉用户先用文字描述

关键岔路:seedream vs seedance vs mermaid

默认倾向 seedream / mermaid(静态够用就别上动态):

• 用户要的是单张图(封面 / 配图 / 示意图)→ seedream
• 用户要的是结构/流程(节点关系 / 时序 / 架构)→ mermaid

反向选 seedance(满足任一):

• 用户明确说视频/动画/动起来/做个 video(而非"画一张" / "做个图")
• 内容本身离不开运动:水流 / 火焰 / 旋转 / 镜头扫过场景 / 角色动作
• ppt 引子页要视觉冲击 + 时间维度(2-3s 短动画开场)
• 用户先做了静态图,明确说"想动起来" / "加运动感"

模糊时主动问一句:

你这是想要 一张静态图(seedream,¥0.22,3-5 秒出图),还是 一段短视频(seedance,¥4 起,等 Fast 30-90s / Pro 2-3min)?静态图够的话省钱省时间。

诊断模糊度 — 六维清单(运动是新增的必填维)

维度	缺失信号
主体 What	"做个混凝土视频" → 视频里有什么?试块 / 楼板 / 工程现场 / 微观裂纹?
运动 Motion ⭐	视频特有,必问 — 主体在做什么?(浇筑 / 凝固 / 裂开 / 旋转 / 镜头扫过)。没运动 = 应该走 seedream。
场景 Where	工地 / 实验室 / 抽象空间 / 极简白底?
镜头 Camera	镜头怎么动?(固定 / 跟随 / 推近 / 拉远 / 环绕 / 俯视下降)。AI 视频对镜头描述很敏感,不写默认随机晃动
风格 Style	写实摄影 / 工业 CG / 扁平 2D 动画 / 水墨 / 赛博朋克 / 学术示意?
时长 + 分辨率 + 比例	时长:4-15s,默认 5s(短=便宜)。分辨率:fast 仅 480p/720p,默认 720p。比例:ppt 16:9 / 短视频 9:16 / 头像 1:1。

评估规则:

• 6 维填齐 / 缺 ≤1 → 可以直接装配 prompt 调用
• 运动维不能省 —— 没运动就劝退到 seedream(¥0.22 vs ¥4,差 18 倍)
• 缺 2 维及以上 → 先问再画
• 时长、分辨率、比例三选一缺即追问;没说时长就默认 5s 是错的,要问"4s 短演示 / 5s 默认 / 8s 中等 / 12s+ 长镜头?",时长直接决定钱:cost ≈ ¥4 × duration/5 × resolution_factor

一次性给推断 + 待确认项(不要一个个问)

模糊时一次摆出推断,让用户改或确认:

你说"做个混凝土浇筑的视频",我打算这样画:

• 主体:工地上正在浇筑混凝土的楼板
• 运动:混凝土从泵车软管流出注入模板,工人手持振动棒来回插入
• 场景:工地中景,远处有塔吊
• 镜头:固定俯视 + 缓慢推近模板中心
• 风格:写实工程纪录片
• 时长 / 分辨率 / 比例:5s / 720p / 16:9(ppt 用) — ¥4.00,等 Fast 30-90s / Pro 2-3min

这样画可以吗?或者告诉我:想突出什么?(浇筑工艺细节 / 振动棒动作 / 大场面气势 / 慢动作)

装配 prompt — 用户拍板维度后

把前 5 维拼成自然中文 prompt 文本(运动 / 镜头是新增重点),时长 / 分辨率 / 比例走参数:

工地上正在浇筑混凝土的楼板,混凝土从泵车软管流出注入模板,
工人手持振动棒来回插入,固定俯视镜头缓慢推近模板中心,
写实工程纪录片风格,正午阳光

要点:

• 运动描述具体 —— "流动 / 旋转 / 推近 / 倾倒",不要"动起来"这种无信息词
• 镜头单独成句 —— "固定俯视 / 缓慢推近 / 环绕一周 / 跟随主体平移";不写默认镜头随机晃动
• 不要堆形容词 —— 模型理解动作 > 形容词
• 不要写否定 —— "no shaking, not blurry" 反向起效;Seedance 不支持 negative prompt
• 主体放最前,镜头 / 风格放后

⛔ 调 tool 前再过一道:把最终 prompt + 参数贴给用户

装配完后立即用对话消息把最终结果贴出来 + 等用户明确确认。装配 ≠ 授权调用。

格式建议(代码块包起来,清晰可读):

我准备调 seedance,参数如下:

prompt: 工地上正在浇筑混凝土的楼板,混凝土从泵车软管流出注入模板,
        工人手持振动棒来回插入,固定俯视镜头缓慢推近模板中心,
        写实工程纪录片风格,正午阳光
resolution: 720p
ratio: 16:9(ppt 横版)
duration: 5 秒
watermark: false
generate_audio: false(静音视频,后期 ppt 加 BGM)
预计花费: ¥4.00
预计等待: 30-90 秒

这样开烧?要改什么?(改 prompt 文字 / 改时长 / 换比例 / 降到 480p 省钱 / 开 audio 加 AI 配音)

然后 ⛔ BLOCKING:等用户明确回复。

为什么强调 —— ¥4 一段视频,用户没机会在调用前看清楚 prompt 的话,生成后只能事后看视频反推哪句话错了,改一次又是 ¥4 + 1.5 分钟。一次对话往返(免费)避免一次错片(¥4 + 90s 等待),是最划算的强制门。

参数取舍

resolution(分辨率)

选项	像素 (16:9)	适用场景	与 720p 价格比
480p	854×480	短演示 / 邮件附件 / 低带宽预览 / 省钱档	~0.47x(便宜一半)
720p(默认)	1280×720	ppt 嵌入 / 公众号 / 一般演示	1.0x(¥4 / 5s)
1080p	1920×1080	fast 不支持,会报 [Error];仅 pro 可用	—

默认 720p 是合理的"够用挡";预算紧 / 试效果用 480p;fast 上限就是 720p,用户要 1080p+ 要切到 pro variant(yaml 里没配 pro 时直接告诉用户)。

duration(时长)

时长	适用	720p 16:9 估价
4s	最短,纯展示 / 转场 / loop	~¥3.20
5s(默认)	标准短视频 / ppt 引子	~¥4.00
8s	中等叙事 / 完整动作	~¥6.40
12s	长镜头 / 复杂场景	~¥9.60
15s	上限 / 完整 plot	~¥12.00

线性扩展(每秒 ~¥0.8 @ 720p);短=便宜=快,无明确叙事需求默认 5s。4s 是最低,< 4 报错。

ratio(比例)

比例	适用
16:9(默认)	ppt / 横版演示 / 一般用途
9:16	短视频 / 抖音 / 小红书 / 手机海报
1:1	社交头像 / Instagram
4:3	老电视 / 复古
3:4	杂志竖版
21:9	电影超宽 / Banner
adaptive	模型自己选

默认 16:9 适合 90% ppt / 申报 / 公众号场景。比例错了后期裁切很难还原构图 —— 不问用途默认 16:9 也比默认 1:1 强(seedream 那边有 1:1 误区,这里别犯)。

watermark

默认	何时改
false	默认无水印(申报 / ppt / 客户交付都不该带);仅当用户明确说"加水印"才传 true

generate_audio(Seedance 2.0 旗舰特性)

默认	何时开
false	默认关 —— 控成本 + 大多数 ppt / 申报场景用静音视频(后期配音 / 当背景视频)。模型还要算音轨,开启 cost 会高于纯视频估算(具体增幅未实测,首次开时盯一下返回的 tokens)。
true	用户明确要带声音的视频:广告 / 短剧 / 角色对白 / 配乐场景。调用前必须告诉用户"开启 audio,cost 会高于估算 ¥X"并等确认。

prompt 写法变化:开 generate_audio=true 时,prompt 里要描述声音是什么(背景音 / 音效 / 对白台词具体说啥 / 音色),否则模型随机配,效果难控:

... 背景音「鲜切现摇」,女生音色,轻快鼓点卡点

参考火山方舟官方 r2v 例子(r2v_tea_*):每个镜头段都明示"背景音 XX / 卡点 XX / 音效 XX"。不写 = 不可预期。

调用范式

前置条件:用户已经看过最终 prompt + 所有参数,明确回复"可以" / "OK" / "出片吧" 之类。没看到这个确认就不要调。

seedance 是 tool 不是 skill 函数,直接调,不要 run_python 包一层:

seedance(
    prompt="工地上正在浇筑混凝土的楼板,混凝土从泵车软管流出注入模板,工人手持振动棒来回插入,固定俯视镜头缓慢推近模板中心,写实工程纪录片风格,正午阳光",
    resolution="720p",     # 可省,走默认
    ratio="16:9",          # 可省
    duration=5,            # 可省
    watermark=false,       # 可省
)

调用是同步阻塞 Fast 30-90s / Pro 2-3min —— tool 内部 submit 后轮询直到 succeeded,期间 LLM 卡住。这不是 bug,告诉用户"提交了,等 30-90 秒"再耐心等返回。

返回串首行是 [seedance] model=... · resolution=... · ratio=... · duration=Xs · cost=¥... · elapsed=...s —— 原样保留给用户(SPA 会 parse 挂徽章)。第二行 saved: <相对路径> 是产物路径,告诉用户。

产物自动落 <task_dir>/videos/<时间戳>-<rand>.mp4 + 同名 .meta.json(prompt / 参数 / cost / tokens / cgt_id 全 snapshot)。

失败 / 不满意后怎么办

不要原 prompt 重发!那是 ¥4 一发的浪费。

现象	原因	解药
主体动作不对	运动描述太抽象("动起来"→ 无信息)	用具体动词:"从软管流出 / 来回插入 / 缓慢上升"
镜头不稳 / 随机晃动	没指定镜头	加"固定镜头" / "缓慢推近" / "环绕一周";尤其要明确镜头是否固定
主体被切掉	比例与构图不匹配	改 ratio 或在 prompt 里写"全景 / 中景 / 主体居中"
风格不对	风格词位置太靠后 / 缺少	风格词放 prompt 前 1/3:"写实工程纪录片风格,xxx"
时长不够讲完动作	duration 太短	4s 适合单一动作,多步骤动作至少 8s
[Error] seedance API 报错(传 1080p 时)	fast 不支持 1080p+	降到 720p 重试;或换 pro variant(yaml 加配置)
[Error] seedance 轮询超时	队列拥堵 / 服务异常	等几分钟再试;cgt_id 在 24h 内仍可手工 GET 拉结果
[Cancelled]	用户点了停止	告诉用户:远端任务可能仍在跑,Volcengine 失败/成功才计费,若仍出片可能产生费用
出现奇怪文字	Seedance 文字渲染不稳	prompt 里不要要求画文字 / 字幕;字幕后期 ppt 加

先口头跟用户对齐改哪一维,再发新调用 —— 不要"再画一段试试"连续烧钱。

产物处理

生视频完成后:

• 把 saved: videos/xxx.mp4 路径告诉用户(SPA 会自动 inline 播放器,点击可全屏)
• 如果是做 ppt,提醒用户 python-pptx 可以 add_movie 嵌入 mp4(但导出 pdf 时视频会丢,改截关键帧 + 链接)
• 用户说"换一段" → 走上节的"对齐改哪一维"流程,不要默认重发
• 用户说"再来几段备选" → 先确认:"备选 N 段会花 ¥{4 × N} + 等 {N × 60}s,确认?"

反模式

• ❌ 没把最终 prompt+参数贴给用户看就直接 tool call —— 比 imagegen 更严格的铁律(¥4 vs ¥0.22)
• ❌ 用户回"看起来不错"就当确认调 tool —— 模棱两可必须追问到明确"是 / OK / 画吧"
• ❌ 运动维度跳过(=应该走 seedream 却走 seedance) —— 浪费 18 倍价钱
• ❌ 用户没主动要视频就装饰性生成
• ❌ 用户说"做个动画" 直接拿这 4 个字当 prompt 调用 —— 六维清单至少先问 2 轮
• ❌ 一个个问"主体?""镜头?" —— 一次性摆推断 + 让用户改
• ❌ 不问时长直接默认 5s —— 5s 是合理默认但要让用户知道有 4-15s 区间;长视频(>8s)开调用前必须强调成本
• ❌ 不问分辨率上 720p —— 试效果阶段先 480p(便宜一半)
• ❌ 同一目的不满意连续重发 —— 1 次错 = ¥4 + 60s,2 次连发 = ¥8 + 2min,先校准 prompt 再调
• ❌ prompt 写"动起来 / 有动感" —— Seedance 不靠形容词,要具体动词
• ❌ prompt 里写否定 "no shaking, not blurry" —— Seedance 不支持 negative,反向起效
• ❌ 让用户在 seedream / seedance 之间默默替他决定 —— 模糊就一句话问明白
• ❌ phase 1 拿用户已生成的图试图 i2v —— 当前不支持,明确告诉用户
• ❌ 用户没说要声音就把 generate_audio 设 true —— 多花钱且大概率配出不合用户预期的随机音效;开它前必须问"要 AI 配音吗?cost 会高于估算"
• ❌ 用 run_python 调 requests 裸打豆包 API —— 走 seedance tool(已封装异步轮询 + 计费 + 落盘 + meta + cancel)

输出

调完告诉用户:

• 文件相对路径(videos/xxx.mp4)
• 本次成本(¥X.XX,从 banner 抽)
• 用的 prompt 摘要(主体 / 运动 / 镜头 3 件套)
• 一句"要换方向 / 调镜头 / 加长时长再来一段吗?"