seedance-cli

seedance-cli

用于在 Volcengine Ark 上生成 Seedance 2.0/2.5 视频的命令行界面。

二进制文件名：seedance。使用 Rust 编写。配置存储在 ~/.config/seedance/config.toml。任务历史记录存储在本地 SQLite 数据库 ~/.config/seedance/tasks.db 中。

同一代码仓库还提供用于图像生成的 seedream 二进制文件——请参阅 seedream-cli 技能。

---

快速开始

# 1. Configure API key (interactive)
seedance config init

# 2. Generate a video (text-to-video)
seedance generate "A cat sits on a windowsill watching rain fall outside"

# 3. Generate and wait for result
seedance generate "Sunset over mountain lake, slow drone pullback" --wait

# 4. Generate with full control
seedance generate "Product bottle on marble surface, slow orbit" \
  --model standard --duration 8 --ratio 16:9 --resolution 1080p --wait

---

安装

# From source
cargo install --path .

# Verify
seedance --version

---

环境

变量	用途
ARK_API_KEY	API 密钥（设置后会覆盖配置文件中的值）

优先级：ARK_API_KEY 环境变量 > config.toml 中的 api_key。

---

命令

seedance generate — 创建视频

核心命令。支持 T2V、I2V、V2V 和 R2V 工作流。

seedance generate <PROMPT> [OPTIONS]

PROMPT 可以是字面字符串，也可以是 @file.txt，用于从文件读取内容。

生成选项

标志	简写	默认值	说明
--model	-m	standard	模型：standard/fast（2.0）、2.5，或原始 Ark 模型 ID
--duration	-d	5	时长（秒）。2.0：4–15。2.5：4–30，或 -1（由模型选择）
--ratio	-r	16:9	纵横比（16:9 9:16 4:3 3:4 21:9 1:1 adaptive）
--resolution		1080p	分辨率（480p 720p 1080p）。2.5 仅支持 480p/720p
--output-format			输出容器：mp4（默认）或 mov——仅适用于 2.5
--seed			用于保证可复现性的随机种子
--watermark		false	添加水印
--audio-gen		false	启用原生音频生成
--return-last-frame		false	将最后一帧作为图像返回
--callback			Webhook 回调 URL
--web-search		false	启用 Web 搜索工具（仅限文本输入）
--service-tier			服务层级：flex 表示离线推理

素材输入（I2V / V2V / R2V）

标志	简写	可重复	上限	说明
--image	-i	是	9	图像参考（URL 或本地路径）
--video	-v	是	3	视频参考（URL 或本地路径）
--audio	-a	是	3	音频参考（URL 或本地路径）
--first-frame		否	1	首帧图像（角色：first_frame）
--last-frame		否	1	尾帧图像（角色：last_frame）

所有类型的文件总数：最多 12 个（12 规则）。

本地文件会自动转换为 base64 数据 URI。支持的格式：JPG、PNG、WEBP（图像），MP4、MOV（视频），MP3（音频）。

素材 URL： 虚拟形象和已获授权的真人素材可通过 asset://<asset-id> 传入任意 --image、--video 或 --audio 标志。

等待与输出选项

标志	简写	默认值	说明
--wait	-w	false	等待完成并自动下载
--output	-o		输出文件路径（默认值：seedance_<id>.mp4）
--timeout		300	最长等待秒数（搭配 --wait 使用）
--poll-interval		10	轮询间隔秒数
--strict		false	超时时返回退出码 2（用于 CI）

输出格式选项

标志	简写	说明
--quiet	-q	安静模式：仅输出 task_id 或最终文件路径
--json		JSON 输出

---

seedance extend — 延长或衔接视频

向前或向后延长视频，或将 2–3 个片段衔接为一个连续视频。可直接传入本地视频文件。超过 min(5s, --duration) 的视频会在上传前自动从末尾裁剪（需要安装 ffmpeg）。

使用 --model 2.5 时，会改为提交原生 extend 任务：不会进行 5s 裁剪（所有片段总时长最长为 30s），画面比例固定为 adaptive，时长为 4–30 或 -1。

seedance extend --source-video <VIDEO>... <PROMPT> [OPTIONS]

传入 1 个视频以向前或向后延长，或传入 2–3 个视频以衔接多个片段。

标志	简写	默认值	说明
--source-video	-s	（必填）	源视频文件（1–3 个，可重复指定）。过长时会自动裁剪
--model	-m	standard	模型变体
--duration	-d	5	时长（4–15s）
--ratio	-r	16:9	画面比例
--resolution		1080p	分辨率
--audio-gen		false	启用音频生成
--watermark		false	添加水印
--return-last-frame		false	返回最后一帧（用于继续串接延长任务）
--seed			随机种子
--image	-i		额外的图像参考（可重复指定）
--wait	-w	false	等待并自动下载
--output	-o		输出文件路径
--timeout		300	最长等待秒数
--strict		false	超时时返回退出码 2
--quiet / --json			输出格式

示例：

# Forward extension (auto-trims if video > 5s)
seedance extend -s input.mp4 "角色走出房间，镜头跟随" --duration 8 --wait

# Backward extension
seedance extend -s source.mp4 "向前延长视频1，镜头从远处推近" --wait

# Bridge 3 clips (each auto-trimmed to min(5s, duration))
seedance extend -s clip1.mp4 -s clip2.mp4 -s clip3.mp4 \
  "视频1打开门，进入室内，接视频2，镜头推进，接视频3" \
  --duration 10 --audio-gen --wait

# Chain generation with return-last-frame
seedance generate "开场：日出" --wait -o opening.mp4
seedance extend -s opening.mp4 "中段：城市苏醒" --duration 8 --wait -o middle.mp4
seedance extend -s middle.mp4 "结尾：人潮涌动" --duration 8 --wait -o ending.mp4

---

seedance edit — 编辑现有视频

编辑已完成的视频：替换主体、添加/移除物体、重绘区域。根据任务 ID 自动解析源视频 URL。

使用 --model 2.5 时，此命令会提交原生 edit 任务：时长/比例自动沿用源视频（忽略 --duration/--ratio）。

seedance edit <SOURCE_TASK_ID> <PROMPT> [OPTIONS]

标志	短选项	默认值	描述
--model	-m	standard	模型变体
--duration	-d	5	时长（4–15s）
--ratio	-r	16:9	纵横比
--resolution		1080p	分辨率
--audio-gen		false	启用音频生成
--watermark		false	添加水印
--seed			随机种子
--image	-i		用于替换/添加的图像（可重复）
--audio	-a		音频参考（可重复）
--wait	-w	false	等待并自动下载
--output	-o		输出文件路径
--timeout		300	最长等待秒数
--strict		false	超时时以状态码 2 退出
--quiet / --json			输出格式

示例：

# Replace subject
seedance edit cgt-abc123 "将视频1中的香水替换成图片1中的面霜，运镜不变" \
  --image cream.jpg --duration 5 --audio-gen --wait

# Modify attribute
seedance edit cgt-abc123 "将面霜颜色修改为白色" --ratio 16:9 --wait

# Add element
seedance edit cgt-abc123 "在桌面右侧添加一杯咖啡" --wait

---

seedance status — 检查任务状态

seedance status <TASK_ID> [OPTIONS]

标志	默认值	描述
--json	false	JSON 输出
--wait	false	持续轮询，直到任务完成
--timeout	300	最长等待秒数（配合 --wait 使用）

---

seedance download — 下载已完成的视频

seedance download <TASK_ID> [OPTIONS]

标志	短选项	描述
--output	-o	输出文件路径（默认：seedance_<id>.mp4）

---

seedance list — 查看任务历史

seedance list [OPTIONS]

标志	短选项	默认值	描述
--limit	-n	20	任务数量
--status			按状态筛选
--json		false	JSON 输出

---

seedance cleanup — 清理 TOS 临时文件

删除过期的 TOS 临时文件（在 extend 或 generate --video 期间上传的文件）。每个上传文件都会带有一个 x-amz-meta-expire-at 元数据标头，其过期时间设为上传后 8 小时。此命令会列出并删除 seedance-cli/ 前缀下的所有对象。

seedance cleanup

需要设置 TOS 环境变量（TOS_ACCESS_KEY、TOS_SECRET_KEY、TOS_BUCKET）。可随时安全运行——只会删除临时上传文件，不会删除用户数据。

提示： 添加到 crontab 中以自动清理：

0 */4 * * * seedance cleanup

在 --wait 时自动清理： extend --wait 成功完成后，会立即删除源视频临时文件——无需运行 cleanup 来清理这些文件。

---

seedance config — 管理配置

seedance config init          # Interactive setup wizard
seedance config show          # Display all settings
seedance config get <KEY>     # Get a single value
seedance config set <KEY> <VALUE>  # Set a single value

可用键：api_key、base_url、model、resolution、ratio、duration、output_dir。

---

Seedance 2.5

使用 --model 2.5（上游模型 doubao-seedance-2-5-260628，于 2026-08-07 在 Ark 上线）。模型 ID、duration: -1 和 mov 输出均已通过实时 API 验证。

能力	2.0	2.5
时长	4–15s	4–30s，或 -1（由模型选择最佳时长）
分辨率	480p / 720p / 1080p	仅支持 480p / 720p（不支持 1080p — 已通过错误信息验证）
参考素材	9 张图片 / 3 个视频 / 3 个音频（12 项规则）	总计 50 项：30 张图片 + 10 个视频 + 10 个音频；音频可以是唯一的参考素材
任务类型	生成	生成 / 编辑 / 延长（原生支持）
输出格式	mp4	mp4 / mov（H.264 + yuv444p + PCM — 更适合调色和抠像）
音频	可选启用	显式发送 --audio-gen（2.5 的服务端默认值为 true）

# 30s max length, model picks duration, mov delivery
seedance generate "One-take cinematic hallway dolly shot" \
  --model 2.5 --duration -1 --resolution 720p --output-format mov --wait

原生延长（2.5）

seedance extend --model 2.5 会提交原生的 extend 任务：源片段不会被裁剪至 5s（1–3 个片段的总时长最多为 30s），比例会强制设为 adaptive（与源素材匹配），时长接受 -1。

原生编辑（2.5）

seedance edit --model 2.5 会提交原生的 edit 任务：时长和比例会自动沿用源视频（--duration/--ratio 将被忽略，并附带说明）。支持通过提示词替换、添加或移除对象，以及编辑音轨。

⚠️ 在 2.5 上，编辑/延长任务按源素材 + 输出总时长计费。720p 下，2.5 每秒的费用比 2.0 高约 37%。

---

提示词工程指南

Seedance 2.0 在内部将空间层（画面中有什么）与时间层（事物如何随时间变化）分开处理。优秀的提示词是工程指令，而不是文学描述。

参考语法

语法	用法
@图片N / @视频N / @音频N	素材引用（按 CLI 中 --image/-s/--audio 的顺序编号，从 1 开始）
<主体N>@图片N	将主体绑定到其参考图片
将 @图片N 中的[特征]定义为 <主体N>	定义可复用的主体标签（适用于多场景）

• 切勿在动作描述中使用原始素材 ID。
• 始终在 @图片N 与后续动词之间加入名词：错误：@图片1跑向…；正确：<主体1>@图片1 跑向…。

任务分类

类型	使用场景	提示词模式
参考	动作/风格/角色迁移	参考 @图片N 中的<主体N>，生成…
编辑	局部替换、移除、修改	严格编辑 @视频1，将其中的<原特征>修改为<新特征>
延长	延续剧情、衔接片段	向后延长 @视频1，生成… / @视频1，<过渡>，接@视频2
合成	参考一个素材，编辑另一个素材	参考 @图片1 的[维度]，严格编辑 @视频2

⚠️ 编辑/延长任务：直接使用 @视频N，不要使用 参考 @视频N — 后者会被视为参考任务。

八个核心要素

1. Subject     — who/what, identity (use <主体N>)
2. Action      — verb + physics consequence, body-part detail + degree quantified
3. Scene       — environment, lighting, time of day
4. Lighting    — color temperature, quality, direction
5. Camera      — ONE move only (push/pull/pan/track/fixed/follow)
6. Style       — ONE primary style anchor (film/realistic/anime/cyberpunk)
7. Quality     — resolution, detail level, texture
8. Constraints — watermark/logo/subtitle suppression, stability, clone prevention

两种输出路径

路径 A — 简单（一个段落）： 适用于单镜头、编辑、延长、移动任务。用一个连贯段落描述，并在文中加入约束。

[Task pattern], [subject + asset binding], [scene + brief action], [style + constraint pack]

路径 B — 复杂（三个段落）： 适用于包含 ≥2 个场景的叙事序列。必须分成三个完整段落：

1. 整体设定 + 主体定义 — 氛围、所有 <主体N> 绑定、镜头参考
2. 场景拆分 — 镜头1 / 镜头2 / 镜头3 …，每个镜头包含镜头→动作→位置→音频。每个镜头只使用一种镜头运动。不得使用绝对时间戳（0–3s 不会生效）。
3. 风格 + 约束包 — 画质、稳定性、抑制字幕/水印、防止克隆

默认约束包（始终附加）

画面稳定无变形，人物面部稳定，五官清晰，动作连贯自然，不僵硬，无穿模无卡顿。
保持无字幕，不要生成水印，不要生成 Logo。
高清电影质感，色彩自然，光影柔和。

对于多角色场景，添加：禁止出现双胞胎/同款分身，同画面仅保留单个对应人物。

重要注意事项

• ❌ 负面提示词 — 描述你想要的内容，而不是你不想要的内容
• ❌ 绝对时间戳（0–3s）— Seedance 2.0 无法可靠地遵循这些时间戳
• ❌ 一个镜头中使用多个镜头运动 — 每个镜头选择一种
• ❌ 高冲击力动作（冲刺、大幅跳跃、剧烈翻滚）— 优先使用缓慢、连续的微动作
• ❌ 抽象的情绪词 — 将其转化为外在的身体细节（悲伤 → 肩膀颤抖、眼睛发红）

---

工作流模式

文本生成视频（T2V）

seedance generate "A glass perfume bottle on white marble. Smooth 360-degree orbit camera. Soft studio key light." \
  --duration 8 --ratio 16:9 --wait

图像转视频（I2V）

seedance generate "Character walks forward slowly, wind blows hair" \
  --first-frame character_pose.png --duration 5 --wait

多图参考转视频（R2V）

seedance generate "Character A throws a punch at Character B" \
  --image charA.png --image charB.png --duration 8 --wait

视频转视频（V2V）并进行风格迁移

seedance generate "Match the camera movement and editing style from reference" \
  --video reference_clip.mp4 --image character.png --duration 10 --wait

音频驱动生成

seedance generate "Character speaks directly to camera, medium close-up, locked" \
  --audio dialogue.mp3 --image character.png --audio-gen --duration 8 --wait

音乐节拍同步

seedance generate "Scene images transition on musical downbeats, energetic pacing" \
  --image scene1.jpg --image scene2.jpg --image scene3.jpg \
  --audio music_track.mp3 --audio-gen --duration 10 --wait

视频延长（向前）——快捷方式

seedance extend -s source.mp4 "角色缓步走出房间，镜头跟随" --duration 8 --wait

# Equivalent base-layer command:
seedance generate "向后延长视频1，角色缓步走出房间，镜头跟随" \
  --video source.mp4 --duration 8 --wait

视频延长（多片段衔接）——快捷方式

seedance extend -s clip1.mp4 -s clip2.mp4 -s clip3.mp4 \
  "视频1中拱形窗户打开，进入室内，接视频2，镜头进入画内，接视频3" \
  --duration 8 --audio-gen --wait

视频编辑——快捷方式

seedance edit cgt-abc123 "将视频1礼盒中的香水替换成图片1中的面霜，运镜不变" \
  --image cream.jpg --duration 5 --audio-gen --wait

# Equivalent base-layer command:
seedance generate "将视频1礼盒中的香水替换成图片1中的面霜，运镜不变" \
  --video original.mp4 --image cream.jpg --duration 5 --audio-gen --wait

链式生成——使用 Extend

seedance generate "开场：日出照亮山脉" --wait -o opening.mp4
seedance extend -s opening.mp4 "中段：城市苏醒，车流涌动" --wait -o middle.mp4
seedance extend -s middle.mp4 "结尾：人潮中一个女孩回头微笑" --wait -o ending.mp4

首尾帧（带锚点的 I2V）

seedance generate "角色从站立过渡到奔跑姿势" \
  --first-frame pose_start.png --last-frame pose_end.png \
  --duration 5 --wait

网络搜索（仅文本）

seedance generate "微距镜头对准叶片上翠绿的玻璃蛙，焦点从皮肤转移到透明腹部" \
  --web-search --duration 11 --wait

虚拟 Avatar

seedance generate "图片1中美妆博主面带笑容，向镜头介绍图片2中的面霜" \
  --image "asset://asset-20260401123823-6d4x2" --image product.jpg \
  --audio-gen --ratio adaptive --duration 11 --wait

离线推理

seedance generate "A cinematic landscape shot" \
  --service-tier flex --duration 10 --wait

从文件读取提示词

# Write a complex prompt in a text file
echo '古风仙侠场景，白衣剑客凌空而起，剑光如虹划过夜空，远山云海翻涌。升格慢动作，仰拍视角。' > prompt.txt

seedance generate @prompt.txt --duration 10 --ratio 16:9 --wait

使用种子变化进行批量生成

for seed in 1000 1001 1002 1003 1004; do
  seedance generate "Sunset over ocean, golden light, slow pan right" \
    --seed $seed --duration 5 -q
done

发起后不等待，稍后下载

# Submit task (returns immediately)
TASK_ID=$(seedance generate "A dramatic scene" -q)

# ... do other work ...

# Check status later
seedance status $TASK_ID

# Download when ready
seedance download $TASK_ID -o final_output.mp4

---

CI / 脚本集成

在自动化中使用 --quiet、--json 和 --strict：

# CI pipeline: generate, wait, fail on timeout
TASK_ID=$(seedance generate "Product ad scene" --wait --strict --timeout 600 -q)

# JSON output for parsing
seedance status $TASK_ID --json | jq '.status'

# List recent failures
seedance list --status failed --json | jq '.[].task_id'

---

任务状态

状态	终态	描述
submitted	否	服务端已收到任务
queued	否	正在等待进入生成队列
running	否	正在生成视频
succeeded	是	生成完成
failed	是	生成失败
expired	是	任务结果已在服务端过期
cancelled	是	任务已取消

---

退出代码

代码	含义
0	成功
1	错误（API 失败、参数无效等）
2	超时（仅使用 --strict 时）

---

Agent 注意事项

1. **单次工作流始终使用 --wait。**不使用该选项时，generate 会立即返回，且只包含 task_id。视频尚未准备就绪。
2. **编写脚本时使用 -q。**静默模式仅输出 task_id（生成时）或文件路径（下载时），不输出其他内容。
3. **本地文件会自动上传。**将本地路径传给 --image、--video、--audio，CLI 会处理 base64 编码。无需手动上传。
4. **@file.txt 用于较长的提示词。**带有特殊字符的中文提示词更容易通过文件管理。
5. **--strict 适用于 CI。**不使用该选项时，超时只是软警告（退出代码为 0）。使用该选项时，超时会以代码 2 退出，以便流水线捕获。
6. **使用种子确保可复现性。**相同种子 + 相同提示词 + 相同模型 = 相同输出。可用于 A/B 测试和迭代。
7. 配置优先级：ARK_API_KEY 环境变量会覆盖 config.toml。适用于通过环境变量设置密钥的 CI。
8. **12 个文件限制：**文件总数（图像 + 视频 + 音频 + first_frame + last_frame）不得超过 12。CLI 会在发送前验证。
9. **时长范围为 4–15 秒。**CLI 会拒绝超出此范围的值。
10. **音频必须为 MP3。**其他格式在服务端会静默失败。传给 --audio 前请先转换格式。
11. 对于延长和编辑任务，优先使用 extend/edit 快捷方式，而不是原始的 generate。extend 会自动裁剪超过 min(5s, --duration) 的源视频，并将其作为 base64 上传。edit 会自动将任务 ID 解析为视频 URL。只有原始视频转视频生成才使用带 --video 的 generate。
12. **视频延长由提示词驱动。**模型会根据提示词文本理解延长/编辑/衔接语义。extend/edit 和原始的 generate --video 都依赖此机制——没有专用的 API 标记。
13. **--web-search 仅适用于纯文本输入。**不能与 --image、--video 或 --audio 组合使用。
14. **虚拟 Avatar 使用 asset://。**将 asset://<asset-id> 与 --image/--video/--audio 配合使用。仅适用于 30 天内同一 Volcengine 账户中的素材。
15. **提示词引用使用“素材类型+序号”格式。**在中文提示词中，按内容数组中各类型的顺序引用输入，例如图片1、视频1、音频1。不要在提示词文本中使用素材 ID。