Anil-matcha/Seedance-2-API

概要

Seedance‑2‑APIは、ByteDanceのSeedance動画生成モデル（2.0、2.5、および新しい2 Mini）をラップするPythonライブラリです。このラッパーは公開されているMuAPIエンドポイントと通信し、認証、リクエストのフォーマット、結果のポーリングを処理します。開発者は、テキストプロンプトから映画のようなAI動画を生成したり、静止画をアニメーション化したり、既存のクリップを編集したり、複数の生成にわたってキャラクターの同一性を維持したりすることができます。

---

ライブラリの機能

機能	説明
テキストから動画 (T2V)	自然言語のプロンプトを送信し、高品質な動画（1080p、2.5では4K）を受け取ります。
画像から動画 (I2V)	1つ以上の参照画像を提供すると、モデルがプロンプトに従ってアニメーション化します。
オムニリファレンス (Omni‑Reference)	画像、動画、音声の参照を1つのリクエストに組み合わせ、よりリッチな条件付けを行います。
キャラクターシート (Character Sheets)	1〜3枚の写真から多視点のキャラクター参照を生成し、後のプロンプトで @character:<id> を使用して顔の一貫性を保ちます。
動画編集 (Video‑Edit)	テキストによる説明とオプションの参照メディアを使用して、既存の動画を修正します。
Miniモデル	低コストで高速なバリエーション (Seedance 2 Mini) で、個別のSDK呼び出し (text_to_video_mini, image_to_video_mini) を備えています。
MCPサーバー	他のAIアシスタント（Claude、Cursorなど）が直接Seedanceを呼び出せるようにする、オプションのModel Context Protocolサーバーです。
ユーティリティヘルパー	ファイルアップロード、環境変数ベースのAPIキー処理、およびMuAPIステータスエンドポイントをポーリングする wait_for_completion ヘルパー。

---

始め方

# PyPIからインストール（推奨）
pip install seedance-2-api

.env ファイルを作成し、MuAPIキーを設定します：

MUAPI_API_KEY=your_muapi_api_key_here

基本的な使用例（テキストから動画）：

from seedance_api import SeedanceAPI
api = SeedanceAPI()
submission = api.text_to_video(
    prompt="A cinematic slow‑motion shot of a cyberpunk city in the rain, neon lights reflecting on puddles",
    aspect_ratio="16:9",
    duration=5,
    quality="high",
)
result = api.wait_for_completion(submission["request_id"])
print("Video URL:", result["url"])

同じパターンがMiniモデル (text_to_video_mini) や画像から動画 (image_to_video, image_to_video_mini) にも適用されます。

---

基本概念

• リクエストID (Request IDs) – すべてのMuAPI呼び出しは request_id を返します。api.wait_for_completion(request_id) を使用して、動画の準備ができるまでポーリングします。
• キャラクターワークフロー – 最初に参照写真を使用して api.create_character (または api.character) を呼び出し、シートの生成を待ってから、後のプロンプトで @character:<request_id> を介して参照します。
• MCPサーバー – python3 mcp_server.py を実行してModel Context Protocol経由でラッパーを公開し、他のAIツールがHTTPコードを書かずにSeedanceを呼び出せるようにします。

---

このライブラリを使用すべき場面

• 独自の推論スタックを構築せずに、高忠実度なAI動画 (1080p‑4K) が必要な場合。
• 複数のクリップ間でキャラクターの一貫性を維持することがアプリケーションにとって有益な場合。
• 生の curl 呼び出しよりもシンプルなPythonインターフェースを好む場合。
• ラピッドプロトタイピングや大規模パイプラインのために、低コストなMiniモデルを試したい場合。

---

制限事項と考慮事項

• このライブラリは薄いクライアントであり、すべての重い処理（モデル推論、レンダリング）はMuAPIのサーバー上で行われます。
• リクエストごとにコストが発生します（例：キャラクターシートは$0.18、Miniモデルは約$0.073/秒）。MuAPIアカウントを通じて使用状況を監視してください。
• コンテンツポリシーは競合他社よりも寛容ですが、MuAPIの利用規約を遵守する必要があります。

---

関連プロジェクト (READMEより)

• Seedance‑2‑Spicy‑API, Seedance‑2.5‑Spicy‑API – 「緩和されたモデレーション」ティア用のラッパー。
• MiniMax‑H3‑API, Wan‑3.0‑API – 他のByteDance動画モデル用のラッパー。
• seedance‑2‑mcp, seedance‑2.5‑mcp – MCPサーバーに特化したプロジェクト。
• awesome‑seedance‑*‑prompts – キュレーションされたプロンプト集。

---

要約

seedance-2-api は、ByteDanceのSeedance動画生成モデルのための、本番環境対応のPython SDKです。MuAPIを介して、テキストから動画、画像から動画、キャラクターの一貫性、動画編集、および低コストなMiniバリエーションを提供します。pipでインストールし、MuAPIキーを設定し、高レベルメソッドを呼び出すだけで、わずか数行のコードで映画のようなAI動画を生成できます。