mcn-short-video/project/短视频提示词生成/V1.0/参考skills/seedance2.0-prompt-skill/references/cli-integration.md

Dreamina CLI 集成指南（可选增值）

即梦官方命令行工具 dreamina 的集成规范。Skill 的主输出仍是"可复制的中文提示词"，CLI 执行是可选增值步骤，用户明确说"跑"才执行。

---

0. 设计原则（写在最前，不能违反）

1. 提示词输出是主线，CLI 执行是支线。 任何情况下都要先给出可复制的提示词文本；CLI 跑不通不影响 Skill 可用性。
2. 消耗积分的命令执行前必须警告。 跑之前明确告知模型、分辨率、时长、预估消耗；余额不足（<100）拒跑。
3. 默认保守（模式 A）：生成完提示词后询问用户是否执行，绝不默认跑。
4. 不硬编码模型参数。 以官方 dreamina <cmd> -h 的实时输出为准；本文档只描述当前约定的默认值。
5. 以 submit_id 和 gen_status 判断成败，不看 exit code。
6. 遇到 AigcComplianceConfirmationRequired：引导用户先去 Web 端完成授权，再 retry。
7. 单次对话内连续失败 3 次后必须停下，问用户"问题是提示词还是模型，是否换策略"，避免无脑烧积分。

---

1. 前置检查

调用 CLI 前按顺序验证：

# 1. 命令存在
command -v dreamina || echo "CLI 未安装，访问 jimeng.jianying.com/cli 安装"

# 2. 已登录 + 看余额
dreamina user_credit

user_credit 返回示例：

{
  "total_credit": 5077,
  "user_id": 2107134092516990,
  "user_name": "",
  "vip_level": "maestro"
}

判断规则：

场景	动作
无返回 / 报未登录	提示用户 dreamina login 后再试，暂停执行
total_credit < 100	拒跑，提示充值
total_credit < 500	警告余额偏低，让用户确认是否继续
vip_level 为 maestro / pro / vip	可以用 seedance2.0_vip（1080p 支持）
vip_level 为空 / 普通	降级到 seedance2.0 或 seedance2.0fast，720p

---

2. 命令选型决策树（路径 C）

用户素材只有 1 张图 + 提示词？
├─ 是 → image2video（最轻量，比例自动从图推断）
└─ 否（多图 / 参考视频 / 音频 / @图片1@图片2 多素材 @引用）
    → multimodal2video（全能参考，需手动指定 --ratio）

2.1 image2video（单图场景，路径 C 默认）

典型调用：

dreamina image2video \
  --image='/path/to/scene.jpg' \
  --prompt="$(cat /tmp/dreamina_prompt.txt)" \
  --duration=15 \
  --model_version=seedance2.0_vip \
  --video_resolution=720p \
  --poll=120

关键点：

• 比例自动从输入图推断，不要传 --ratio（传了会报错）
• --prompt 用 $(cat file) 读文件的方式传，彻底避开 shell 转义问题（见第 5 节）
• --duration 支持 4-15，路径 C v2 默认值由 image-to-prompt.md 的"建议时长"推算决定，不再硬编码 15（v2 升级）
• --poll=120 提交后最多前台等 120 秒，超时自动 fallback 到 query_result

2.2 multimodal2video（全能参考场景）

典型调用：

dreamina multimodal2video \
  --image='/path/to/img1.jpg' \
  --image='/path/to/img2.jpg' \
  --prompt="$(cat /tmp/dreamina_prompt.txt)" \
  --ratio=9:16 \
  --duration=15 \
  --model_version=seedance2.0_vip \
  --video_resolution=720p \
  --poll=120

关键点：

• 必须指定 --ratio，可选 1:1, 3:4, 16:9, 4:3, 9:16, 21:9
• --image 可重复多次传多张图（上限 9 张）
• 可选 --video（上限 3）--audio（上限 3，时长 2-15s）
• 至少需要一张 --image 或 --video

---

3. 默认参数约定（Skill 路径 C 用）

参数	默认值	何时改
--model_version	seedance2.0_vip	想快速试片/降本 → seedance2.0fast_vip；无 VIP → seedance2.0
--video_resolution	720p	成品满意后用户要 1080p → 改 1080p（仅 seedance2.0_vip 支持）
--duration	15	用户要更短就按用户的
--poll	120	网络差可调到 180；不想等就设 0
--ratio（仅 multimodal）	跟随路径 C 的比例诊断结果	-

质量 / 速度 / 成本光谱（从高到低）：

seedance2.0_vip (1080p)   ← 最终成片
seedance2.0_vip (720p)    ← 默认
seedance2.0               ← 标准
seedance2.0fast_vip       ← VIP 快速试片
seedance2.0fast           ← 最便宜的试片

---

4. 交互模板（Skill 路径 C Step 4）

生成提示词后，Skill 默认输出这段询问：

---

## 是否直接调用 dreamina CLI 生成？

- **图片**：./scene.jpg
- **模型**：seedance2.0_vip
- **分辨率**：720p（效果满意后可升级 1080p）
- **时长**：15s
- **比例**：自动从图推断（image2video）
- **预计前台等待**：最多 120s，超时转后台轮询

**当前余额**：[运行 user_credit 查到的值] 积分

回复：
- `跑` / `yes` → 直接执行 image2video（默认配置）
- `fast` → 换 seedance2.0fast_vip 试片（更便宜更快）
- `1080p` → 升到 1080p 高质量（仅 seedance2.0_vip）
- `no` / 不回 → 只保留提示词，不执行

用户回复后的处理：

回复	动作
跑 / yes / 执行 / go	按默认配置调用 image2video
fast / 试片	切换 --model_version=seedance2.0fast_vip，其他不变
1080p / 高清	切换 --video_resolution=1080p，警告消耗翻倍
no / 不回 / 其他话题	不执行，保留提示词
提出调整提示词	回到提示词迭代，调整完再次询问

---

5. Shell 转义与提示词传递

问题：Seedance 提示词经常包含中文引号、英文引号、冒号、逗号、换行，直接塞 --prompt="..." 容易翻车。

稳妥方案：写入临时文件 + $(cat ...)

# 1. 把提示词写入临时文件（cat heredoc 避开所有转义）
cat > /tmp/dreamina_prompt.txt <<'PROMPT_EOF'
15秒赛博朋克暴雨追逐，8K超高清...（完整提示词多行都可以）
PROMPT_EOF

# 2. 调用时用 $(cat file) 读入
dreamina image2video \
  --image='/path/to/scene.jpg' \
  --prompt="$(cat /tmp/dreamina_prompt.txt)" \
  --duration=15 \
  --model_version=seedance2.0_vip \
  --video_resolution=720p \
  --poll=120

heredoc 用 <<'PROMPT_EOF'（带单引号）很关键，这样里面的 $ ` \ 全部按字面量处理，不会被 shell 二次解释。

图片路径用单引号包裹（'/path/with spaces/img.jpg'），防空格和特殊字符。

执行完清理临时文件：

rm -f /tmp/dreamina_prompt.txt

---

6. 异步任务处理

6.1 提交成功的识别

提交后 CLI 会返回 JSON（或结构化输出），关键字段：

• submit_id：任务 ID，必须记下来
• gen_status：任务状态（pending / running / success / fail）
• result：成功时包含视频 URL 或本地保存路径

判断：看 submit_id 有没有拿到。不看 exit code。

6.2 Poll 超时的处理

如果 --poll=120 到点还没完成，CLI 会返回当前状态（通常是 running），此时要告诉用户：

任务已提交，submit_id=xxxx
目前仍在生成中，前台等待已超时。可以稍后手动查：

  dreamina query_result --submit_id=xxxx

或者让我稍等 30-60 秒再帮你查一次。

我可以在对话里主动再跑一次 query_result，但不要无脑轮询烧 token。

6.3 失败处理

gen_status=fail 时，读 fail_reason 字段，常见：

fail_reason	含义	处理
AigcComplianceConfirmationRequired	模型需要先在 Web 端完成授权	引导用户去 https://jimeng.jianying.com 对应模型首次使用授权后重试
内容安全 / 合规相关	提示词或图片触发了内容安全	分析提示词，去掉敏感元素重写
配额 / 限流	模型当前 capacity 紧张	建议换 seedance2.0fast_vip 或稍后重试
超时 / 网络	服务端出错	直接重试

---

7. 审计日志建议

每次执行后在对话里简要回显一次执行记录，方便用户回溯：

### 执行记录
- 命令：dreamina image2video
- 图片：./scene.jpg
- 模型：seedance2.0_vip / 720p / 15s
- submit_id：xxxxxxxx
- 状态：success
- 结果：[视频路径或 URL]
- 消耗：[如 CLI 返回了扣分数就写]

---

8. 硬约束（Skill 级 guardrail）

1. 跑之前必须先 user_credit，余额 < 100 拒跑。
2. prompt 中含品牌名 / 真人名 / 政治人物时，即使模型没拦也要先警告。
3. 连续失败 3 次强制停下问用户："问题是提示词还是模型，是否换策略？"
4. 用户没说"跑"就不要跑。 哪怕提示词改了 N 版，也只输出文本。
5. 不要跑 image2video 时传 --ratio（不支持，会报错）。
6. 不要把 --prompt 的内容直接写进命令行字符串，始终走临时文件方案（第 5 节）。

---

9. 常见错误速查

现象	原因	解决
command not found: dreamina	CLI 没装 / PATH 没刷新	重开终端，或 export PATH="$HOME/.local/bin:$PATH"
登录状态丢失	token 过期	dreamina relogin
unsupported ratio	image2video 传了 --ratio	去掉 --ratio，image2video 从图自动推断
1080p not supported	非 seedance2.0_vip 模型用了 1080p	要么换模型，要么改 720p
AigcComplianceConfirmationRequired	模型首次使用未授权	去 Web 端该模型下走一次生成流程授权，再 retry
duration out of range	超出模型支持范围	seedance2.0 家族支持 4-15s
prompt 里的中文冒号变乱码	shell 转义出错	用临时文件方案（第 5 节）
余额充足但秒挂	可能是图片格式 / 大小问题	换 jpg/png，尺寸控制在 2K 以内

---

10. 与其他文档的关系

• 路径 C 提示词生成方法论 → image-to-prompt.md
• 平台基础参数（画幅/时长等限制）→ platform-specs.md
• 实时命令参数以 dreamina <subcommand> -h 为准，本文档仅描述 Skill 约定的默认配置

---

11. 非路径 C 场景的兼容

虽然默认只在路径 C Step 4 激活 CLI 询问，但如果用户在路径 A / B 中明确说"帮我直接跑"，也可以按同样的决策树调用：

• 路径 A（纯文本）→ dreamina text2video（参数类似，-h 现查）
• 路径 B 的逐镜头 → 每个镜头单独调 image2video 或 multimodal2video
• 角色图/首帧图生成 → dreamina text2image / image2image

这些不是当前集成的主线，用户明确要求时现场查 -h 组命令即可。