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 個のクリップをつないで 1 本の連続した動画にします。ローカルの動画ファイルを直接指定します。min(5s, --duration) より長い動画は、アップロード前に末尾から自動的にトリミングされます（ffmpeg のインストールが必要です）。

--model 2.5 を指定すると、代わりにネイティブの extend タスクが送信されます。この場合、5 秒のトリミングは行われず（クリップ全体で最大 30 秒）、アスペクト比は 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～15 秒）
--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～15 秒）
--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 の実行中にアップロードされたファイル）を削除します。アップロードされた各ファイルには、アップロードから 8 時間後に設定される x-amz-meta-expire-at メタデータヘッダーが付与されます。このコマンドは、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。Ark で 2026-08-07 に公開）を使用します。モデル ID、duration: -1、mov 出力はライブ API で検証済みです。

機能	2.0	2.5
長さ	4～15 秒	4～30 秒、または -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 タスクを送信します。ソースクリップは 5 秒にトリミングされず（1～3 個のクリップで合計最大 30 秒）、比率は 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 つのアセットを参照し、別のアセットを編集	参考 @图片1 的[维度]，严格编辑 @视频2

⚠️ 編集／延長タスク：@视频N を直接使用してください。参考 @视频N は使用しないでください。後者は参照タスクとして扱われます。

8 つの基本要素

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

2 つの出力パス

パス A — シンプル（1 段落）： 単一ショット、編集、延長、移動タスク向けです。制約を含めた、流れのある 1 段落にします。

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

パス B — 複雑（3 段落）： 2 つ以上のシーンからなる物語形式の連続シーケンス向けです。完全な段落を 3 つ用意する必要があります。

1. 全体設定と主体の定義 — 雰囲気、すべての <主体N> の紐付け、カメラ参照
2. シーンの詳細 — 镜头1 / 镜头2 / 镜头3 …。各シーンにカメラ→動作→位置→音声を含めます。1 ショットにつきカメラの動きは 1 つにします。絶対タイムスタンプ（0～3 秒など）は使用しないでください。
3. スタイルと制約のセット — 品質、安定性、字幕／ウォーターマークの抑制、複製の防止

デフォルトの制約セット（必ず末尾に追加）

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

複数のキャラクターが登場するシーンでは、禁止出现双胞胎/同款分身，同画面仅保留单个对应人物。 を追加します。

重要な禁止事項

• ❌ ネガティブプロンプト — 望まないことではなく、望むことを説明してください
• ❌ 絶対タイムスタンプ（0–3s）— Seedance 2.0 では確実に従われません
• ❌ 1 ショットに複数のカメラの動き — 1 ショットにつき 1 つだけ選びます
• ❌ 衝撃の大きい動き（全力疾走、大きなジャンプ、激しい転倒）— ゆっくりと連続する小さな動きを優先します
• ❌ 抽象的な感情表現 — 身体的な描写に置き換えます（悲しい → 肩が震える、目が赤くなる）

---

ワークフローパターン

テキストから動画を生成（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

バーチャルアバター

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 を指定した場合のみ）

---

エージェントが注意すべき点

1. 単発のワークフローでは必ず --wait を指定してください。 指定しない場合、generate は task_id のみを返してすぐに終了します。動画はまだ準備できていません。
2. スクリプトでは -q を使用してください。 Quiet モードでは、task_id（generate の場合）またはファイルパス（download の場合）のみが出力され、それ以外は出力されません。
3. ローカルファイルは自動でアップロードされます。 ローカルパスを --image、--video、--audio に渡すと、CLI が base64 エンコードを処理します。手動でアップロードする必要はありません。
4. 長いプロンプトには **@file.txt を使用します。 特殊文字を含む中国語のプロンプトは、ファイルで管理すると簡単です。
5. CI では **--strict を使用してください。 指定しない場合、タイムアウトは警告として扱われ（終了コード 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. 延長や編集のタスクでは、raw generate より extend／edit のショートカットを優先してください。 extend は min(5s, --duration) を超えるソース動画を自動的にトリミングし、base64 としてアップロードします。edit はタスク ID を動画 URL に自動で解決します。raw な動画から動画への生成に限り、--video とともに generate を使用してください。
12. 動画の延長はプロンプト駆動です。 モデルはプロンプトのテキストから延長／編集／ブリッジの意味を理解します。extend／edit と raw generate --video のどちらもこの仕組みに依存しており、専用の API フラグはありません。
13. --web-search はテキストのみの入力でのみ動作します。 --image、--video、--audio とは併用できません。
14. バーチャルアバターには asset:// を使用します。 --image／--video／--audio とともに asset://<asset-id> を使用します。30 日以内に同じ Volcengine アカウントで作成したアセットでのみ動作します。
15. プロンプト内の参照には「素材タイプ＋番号」形式を使用します。 中国語のプロンプトでは、入力を 图片1、视频1、音频1 のように参照してください（番号は content 配列内で種類ごとの順番に付けます）。プロンプトのテキストにアセット ID を使用しないでください。