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 キーを取得してください：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
• ビジュアルスタイル：リアル / アニメーション / 水墨画 / SF / サイバーパンクなど
• 素材：既存の画像・動画・音声、または 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_files 配列内の画像を参照するには、@image_file_1、@image_file_2 などを使用します
• video_files 配列内の動画を参照するには、@video_file_1 などを使用します
• audio_files 配列内の音声を参照するには、@audio_file_1 などを使用します

参照構文の例：

@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 に出力されます。

手動で 1 回問い合わせる場合：

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 を参照してください。