seedance-mcp

Claude Code が BytePlus ModelArk Dreamina Seedance 2.5 で動画を生成できるようにする MCP サーバーです。

Claude Code に平文で動画を依頼すると、BytePlus にタスクを送信し、レンダリングが完了するまでポーリングし、BytePlus が報告するメタデータとともに動画 URL を返します。

1. 機能

MCP stdio 上の 6 つのツール:

間違えやすい部分を処理します: ローカル画像と音声を API が期待する Base64 データ URI 形式にエンコード、リクエスト送信前にモデルごとのパラメータ制限を適用、一時的な障害をバックオフ付きで再試行、API キーをすべてのログ行とエラーメッセージから除外します。

2. 前提条件

• Python 3.11+

• uv — brew install uv または curl -LsSf https://astral.sh/uv/install.sh | sh

• Claude Code 2.x

• API キーと Seedance モデルが有効化された BytePlus ModelArk アカウント。

3. BytePlus の設定

1. API キーを作成: ModelArk コンソール → API キー。

2. モデルを有効化します。 Seedance 2.5 はデフォルトでは有効になっていません。BytePlus では次のいずれかが必要です:

   • アカウント残高が USD 30 を超えている、または

   • USD 30 以上の AI 節約プラン、または

   • 残りクォータのある Seedance リソースパック。

   ModelArk → モデル有効化 → コンピュータビジョン で有効化します。これがないと、キー自体は有効でもタスク作成は認証エラーで失敗します。

3. リージョンを確認します。以下のデフォルトのベース URL は ap-southeast (シンガポール) です。アカウントが別の場所でプロビジョニングされている場合は、BYTEPLUS_BASE_URL を適宜設定してください — あるリージョンで作成されたタスクは別のリージョンからは見えません。

4. インストール

git clone <this repo> ~/code/seedance-mcp   # or just use the directory you already have
cd ~/code/seedance-mcp
uv sync

確認:

uv run pytest -q          # 93 tests, all offline against mocked HTTP
uv run ruff check .

5. .env の設定

cp .env.example .env

次に、必須の 変数を 1 つ入力します:

BYTEPLUS_API_KEY=your-modelark-api-key

その他はすべてオプションで、すでにデフォルト値が設定されています:

BYTEPLUS_BASE_URL=https://ark.ap-southeast.bytepluses.com/api/v3
SEEDANCE_MODEL_ID=dreamina-seedance-2-5-260628

.env は gitignore されています。キーは環境からのみ読み取られます — このサーバーによってディスクに書き込まれることはなく、ログに記録されることもなく、API エラーメッセージからは Claude に届く前に削除されます。

6. Seedance 2.5 モデル ID の選択

Seedance 2.5 は 共有の、普遍的に利用可能なモデル ID です — 専用エンドポイントを作成する必要はありません。デフォルトは:

dreamina-seedance-2-5-260628

dreamina- プレフィックスに注意してください。これは BytePlus の命名における実際の不整合です: 2.x Dreamina モデルにはこれが付きますが、1.x ID には付きません (seedance-1-5-pro-251215)。2.5 に 1.x 形式の ID をコピーするのが、「モデルが見つからない」エラーの最も一般的な原因です。

アカウントの現在の ID は ModelArk モデルリスト で確認してください。

専用エンドポイントを希望する場合 (エンドポイントごとのレート制限、前払い請求、または監視のため)、コンソールで作成し、そのエンドポイント ID を SEEDANCE_MODEL_ID に代わりに設定します:

SEEDANCE_MODEL_ID=ep-20260817120000-abcde
SEEDANCE_MODEL_PROFILE=seedance-2.5

SEEDANCE_MODEL_PROFILE はその場合にのみ必要です: ep-... ID は背後にあるモデルについて何も教えてくれないため、これがないとサーバーはローカルでパラメータを検証できず、すべてを API に渡して検証してもらうことになります。

7. Claude Code への登録

このディレクトリから (絶対パスを使用してください — Claude Code は任意の作業ディレクトリからサーバーを起動します):

claude mcp add \
  --transport stdio \
  --scope user \
  byteplus-seedance \
  -- uv --directory /Users/alban/code/seedance-mcp run python -m seedance_mcp

--scope user はすべてのプロジェクトで利用可能にします。--scope project を使用すると .mcp.json を介してリポジトリのコラボレーターと共有できます。--scope を省略すると現在のプロジェクトのみに適用されます。

サーバーは自身のディレクトリから .env を読み取るため、-e フラグは必要ありません。キーを明示的に渡したい場合:

claude mcp add --scope user byteplus-seedance \
  -e BYTEPLUS_API_KEY=your-key \
  -- uv --directory /Users/alban/code/seedance-mcp run python -m seedance_mcp

8. 確認

claude mcp list

次のような行が期待されます:

byteplus-seedance: uv --directory /Users/alban/code/seedance-mcp run python -m seedance_mcp - ✓ Connected

次に、Claude Code 内で /mcp と入力すると、サーバーとその 6 つのツールが一覧表示されます。次のように依頼します:

最近の Seedance タスクを一覧表示して。

これにより、生成クレジットを消費せずに認証と接続をテストできます — 空のリストは成功です。キーが間違っている場合は、代わりに明示的な HTTP 401 メッセージが表示されます。

実際にファイルをレンダリングするエンドツーエンドのチェックには、§10 の最小コストのレシピを使用してください。

9. Claude Code プロンプトの例

Generate a 10-second 1080p cinematic video of Tokyo at night using Seedance 2.5.

Use ./assets/reference.png as the visual reference and generate a slow cinematic push-in shot.

Create the video and wait until generation finishes.

Generate a 15-second 9:16 vertical clip of a surfer at sunrise, no audio, and give me the URL.

Use ./assets/first.png as the first frame and ./assets/last.png as the last frame,
6 seconds, and wait for it.

Check the status of task cgt-20260817... and download the video if it's ready.

Download task cgt-20260818061514-8t2lv into ./renders/ and keep the last frame too.

Cancel task cgt-20260817... — I queued the wrong prompt.

10. コストとタイミング

生成は出力の秒数に応じて課金され、解像度とモデルによってスケーリングされます。パイプラインが機能することを証明する最も安価な方法は、4 秒の 480p クリップです — 4 秒は Seedance 2.x モデルが受け付ける最短の長さです。

無料チェック、生成クレジットは消費しません:

List my recent Seedance tasks.

最も安価な実際の生成。 Seedance 2.0 mini はアカウント上で最も安価なモデルです。2026 年 9 月 7 日まで実施中のプロモーション期間中、720p 出力は約 USD 0.03/秒から始まり、480p はそれ以下です:

Using Seedance model seedance-2-0-mini-260615, generate a 4-second 480p video, 16:9, no audio,
prompt: "a red balloon floating up against a blue sky". Then wait for it and give me the URL.

Seedance 2.5 デフォルトパスの最も安価なテスト — 2.5 は異なるモデル有効化と異なる価格帯であるため、個別に実行する価値があります:

Generate a 4-second 480p Seedance 2.5 video, 16:9, no audio,
prompt: "a red balloon floating up against a blue sky". Wait for it and give me the URL.

測定ベースライン

2026-08-18 の実際の Seedance 2.5 テキストから動画への実行から:

これが下限です: 参照メディアなしで最短時間、最低解像度です。また、seedance_wait_for_video の期待値を設定します。その 900 秒のデフォルトタイムアウトは、これより一桁重いジョブ向けにサイズ設定されています。

このベースラインからのスケーリングは推定であり、測定ではありません — 使用量は出力秒数とピクセル数に追従するため、10 秒の 1080p クリップは秒数で約 2.5 倍、ピクセル数で約 5 倍、つまりこの実行の約 10 倍になります。計画の見積もりとして扱い、実際の請求と照合してください。

duration のコストの落とし穴

Seedance 2.5 は duration のデフォルトを -1 にしており、モデルが 最大 30 秒 までの任意の長さを選択できるようにします。課金は出力の秒数ごとなので、duration を指定しないリクエストは、意図した 4 秒のテストの約 7 倍のコストになる可能性があります。コストに敏感な実行では、秒数を明示的に指定してください — ツールはそのまま渡し、4 が下限です。

さらに 2 つの小さな注意点: 480p と 720p は現在の 2.5 プロモーション割引の対象外です (1080p のみ割引対象)。そのため、480p は絶対的なコストで最も安価なままです — 割引が単に適用されないだけです。また、no audio は主に生成時間を短縮します。ドキュメントでは価格が下がるとは示されていません。

11. トラブルシューティング

12. サポートされている Seedance 2.5 機能

タスクタイプ (相互排他的 — BytePlus は混合を拒否します):

• テキストから動画へ — プロンプトのみ。

• 画像から動画へ — first_frame、オプションで last_frame。出力はそれらの画像で正確に開始および終了します。

• オムニ参照から動画へ — 最大 30 枚の参照画像、10 本の参照動画、10 個のオーディオクリップ。オーディオのみの入力も許可されます。プロンプト内でアセットを @Image 1、@Video 2 として引用します。3 つのサブタスクをカバー: 参照から動画へ、動画編集、動画拡張 — omni_reference_task_type で制御します。

出力制御

メディア入力

プロンプトは英語、スペイン語、インドネシア語、ポルトガル語、日本語、マレー語、タイ語、アラビア語、ベトナム語、韓国語で動作します。約1000英単語以内に抑えてください。

出力の保存。 seedance_download_videoはタスクIDを受け取り、現在のURLを自身で検索し、ファイルをディスクにストリーミングします。デフォルトは./<task_id>.mp4です。output_pathとしてファイルパスまたは既存のディレクトリを渡します。overwrite: trueなしでは上書きせず、ダウンロードが中断された場合は部分ファイルをクリーンアップし、タスクがreturn_last_frameで作成された場合はinclude_last_frameで終了PNGを取得することもできます。2つの意図的な制限があります。ダウンロードは独自の認証なしHTTPクライアントを介して行われるため、ModelArkキーがストレージホストに送信されることはありません。また、URLホストは.volces.com、.bytepluses.com、または.byteplus.comで終了する必要があります。これはSeedance出力フェッチャーであり、汎用ダウンローダーではありません。

サーバーはまた、modelツール引数またはSEEDANCE_MODEL_IDを介して古いモデルも対象としています — Seedance 2.0 / 2.0 fast / 2.0 mini、1.5 pro、1.0 pro、1.0 pro fast — それぞれを独自の制限に対して検証します（例えば、4Kは2.0では有効ですが2.5では無効です）。

13. 既知のAPI制限

• 生成は非同期です。 同期的に動画を返すものはありません。5～10秒のクリップは通常数分かかり、1080pではさらに長くなります。

• Seedance 2.5ではseedやcamera_fixedは設定できません。 現在のAPIリファレンスでは、両方ともSeedance 1.5 pro、1.0 pro、1.0 pro fastの入力パラメータとしてのみリストされています。このサーバーは2.5ではそれらを明示的なメッセージで拒否し、黙って無視することはありません。代わりにプロンプトでカメラの動作を表現してください。(古いSeedance 1.xのチュートリアルやサードパーティの例ではまだこれらのパラメータが表示されていますが、2.5には適用されなくなりました。)

  実際の2.5実行で観察されたこと: タスクのレスポンスは依然としてseedを報告します（VideoResult.seedとして表示され、例: 80969）。これはモデルが内部で選択するためです。そのため、どのシードがクリップを生成したかは確認できますが、それを再現することはできません — 2.5の生成は再現不可能です。

• Seedance 2.5にはframesはありません。 フレーム数による秒未満の時間指定は1.0 proの機能です。

• ローカル動画はアップロードできません。 画像と音声にはBase64形式がありますが、動画にはありません。

• 64 MBのリクエストボディ上限。 複数の大きな画像をインライン化すると上限に達します。サーバーは送信前にチェックし、URLに切り替えるよう指示します。

• 実際の人間の顔は制限されています。 Seedance 2.xは、実際の人間の顔を含む参照画像や動画を拒否します。ただし、それらが自分のアカウントからの以前のSeedance出力（30日以内）、プリセットのデジタルキャラクター、または許可された実在人物のアセットである場合は除きます。

• キューに入ったタスクのみキャンセルできます。 タスクが実行中になると、完了まで実行されます。

• 出力URLの有効期間は24時間で、Seedance 2.5では100回のダウンロード制限があります。両方の制限は署名付きURL自体に組み込まれています。返されたリンクにはX-Tos-Expires=86400とX-Tos-Max-Requests=100が含まれています。再発行エンドポイントはなく、seedance_list_tasksはそのウィンドウ内にあるURLのみを返すことができます。保存する価値のあるものはseedance_download_videoを使用して保存してください。ウィンドウが閉じた後は、再生成するしかありません。

• タスクレコードは7日間保持されます。

• 参照メディアの時間制限はローカルではチェックされません。 参照動画と音声のクリップあたり（2～30秒）および合計（30秒）の制限はメディアプロービングが必要です。サーバーはそのためのデコーダ依存関係を追加しないため、BytePlusがそれらを強制し、タスクエラーとして報告します。

• 価格と制約は変更されます。 src/seedance_mcp/capabilities.pyの機能テーブルは2026-08-17にBytePlusのドキュメントから転記されました。BytePlusが新しいモデルリビジョンをリリースした場合は再確認してください。

14. プロジェクト構成

seedance-mcp/
├── pyproject.toml
├── README.md
├── .env.example
├── .gitignore
├── src/seedance_mcp/
│   ├── __init__.py
│   ├── __main__.py        # stdio entry point
│   ├── server.py          # the six MCP tools
│   ├── client.py          # BytePlus HTTP client: retries, error parsing
│   ├── payload.py         # request building + validation
│   ├── capabilities.py    # per-model limits from the official docs
│   ├── media.py           # local file -> data URI, with validation
│   ├── models.py          # typed request/response models
│   ├── config.py          # environment configuration
│   └── errors.py          # error types + secret redaction
└── tests/

capabilities.py、payload.py、media.pyは概要でスケッチされたレイアウトへの追加です。文書化されたモデルごとの制約テーブル、リクエストビルダー、メディア処理はそれぞれ実際のロジックと独自のテストを持ち、それらをserver.pyやmodels.pyに折り込むと両方が読みにくくなったでしょう。

15. 出典

上記のすべてのAPI詳細は、現在の公式BytePlusドキュメントに対して検証されています。

• 動画生成タスクの作成

• 動画生成タスクの取得

• 動画生成タスクの一覧表示

• 動画生成タスクのキャンセルまたは削除

• Dreamina Seedance 2.5 チュートリアル

• モデル一覧

• 動画生成APIチュートリアル