RunningHub Seedance 2.0 API のセットアップ：API キー、アセット、および最初の呼び出し

AI Overview

RunningHub Seedance 2.0 API を最も迅速にセットアップする方法は？

RunningHub の API キーを作成し、正確な Seedance 2.0 AI アプリまたはモデルルートを選択して、最小限のリクエストを 1 回送信した後、その taskId をポーリングします。アップロード、ウェブフック、本番環境向けの再試行機能は、この最初の呼び出しが成功した後にのみ追加してください。

AI App API と ComfyUI ワークフローのどちらを使用すべきですか？

入力契約が固定されており、ホスティング済みであることが望ましい場合は、AI App API を使用してください。チームがノード間のマッピングを可視化したり、再利用可能なグラフやアセットの事前準備、あるいはプロジェクト間で変化するモデルステップを必要とする場合は、ComfyUI の OpenAPI ルートを使用してください。

RunningHub における Seedance 2.0 アセット ID とは何ですか？

アセット ID により、対応する Seedance 2.0 ノードが事前に準備された参照を再利用できます。ComfyUI 統合では、単純な ID、asset:// 形式の値、カンマ区切りリスト、または JSON 配列文字列のいずれかを受け入れますが、選択したノードが有効な入力スロットを最終的に決定します。

完了したタスクの URL をすぐにコピーする必要がある理由は何ですか？

RunningHub は、アップロードおよび生成結果に対する一時的なメディアリンクを記録します。承認済みの MP4 およびポスターファイルは、タスクが成功した直後に自社の耐久性のあるストレージへ移動させてください。保存されたタスク ID は、永続的なメディアアーカイブではありません。

最初の呼び出しの前に必要なもの

信頼性の高いセットアップは、以下の 4 つの既知の値から始まります：API リージョン、有効な API キー、正確な AI アプリまたはモデル識別子、およびご自身が管理するストレージ先。関係のないチュートリアルからエンドポイントをコピペし、そのリクエストボディが互換性を持つと想定しないでください。RunningHub は複数の呼び出しスタイルを提供しており、各公開 API 詳細ページは、そのルートに対する正式な契約です。包括的な Seedance 2.0 API ガイド では、一般的な非同期パターンについて説明しています。本ガイドでは、RunningHub に焦点を当てます。

API キーはソース管理外に保管してください。公式の ComfyUI 統合では、推奨される環境変数設定パターンは以下のとおりです：

export RH_API_BASE_URL="https://www.runninghub.cn/openapi/v2"
export RH_API_KEY="replace-with-your-key"

ご自身の RunningHub コンソールおよび最新のドキュメントに表示されるリージョナルベースURL をご利用ください。コンシューマーキーには有資格のメンバーシップが必要な場合があり、エンタープライズキーには異なるアクセスルールが適用されることがあります。カタログでモデルを確認できることと、ご自身のキーでそのモデルを呼び出せることとは、別々のチェック項目として扱ってください。

クレジットを消費する前に、1 つの「受入テストショット（acceptance shot）」を定義してください：1 人の被写体、1 つのアクション、1 つのカメラモーション、1 つの持続時間、および 1 つの配信比率です。プロンプト自体の妥当性に不安がある場合は、まず Seedance 2.0 モデルワークスペース でクリエイティブブリーフをテストしてください。これにより、プロンプト由来の問題と統合由来の問題を分離できます。

最初の呼び出しには、視覚的にシンプルな受入フレームをご利用ください。この新規製品画像では、シルエット、反射、水の動き、背景の安定性を容易に検査できます。これは RunningHub のベンチマークではありません。

適切な RunningHub ルートの選択

本タスクに対して、RunningHub は実用的な 2 つのルートを提供しています。AI アプリルートは、プロバイダーがすでに Seedance 2.0 を名前付き入力を備えた安定したアプリケーションとしてパッケージ化している場合に有効です。このアプリ ID に送信すると、taskId が返されます。一方、グラフ自体が本番ロジックの一部である場合、または Seedance 2.0 アセットヘルパー機能が必要な場合は、ComfyUI の OpenAPI プラグインが適しています。

最初のテストでは、複数のルートを混在させないでください。最小限の AI アプリリクエストで、認証、アプリ識別子、キューへの送信、および結果取得が正しく動作することを検証してください。最小限の ComfyUI 呼び出しでは、動的な nodeInfoList オーバーライドを導入する前に、エクスポート済みワークフローが変更されずに実行されることを検証してください。

公式の RunningHub ComfyUI プラグインは、設定ノード、環境変数、または .env ファイルから設定を読み取ることができます。優先順位は、設定ノード > 環境変数 > .env ファイルです。どのレイヤーからキーが供給されたかを記録してください。そうしないと、チームメンバーが環境シークレットを更新しても、古いノード値が静かに優先され続けてしまう可能性があります。

参照を多用するショットでは、人物、衣装、動物、天候、場所が明確に判別できるようにしてください。この画像は新しい説明用出力であり、公式のモデル比較ではありません。

RunningHub Seedance 2.0 API のステップ・バイ・ステップセットアップ

サービスが実際に所有する変数のみを明らかにするリクエストスケルトンから始めます。RunningHub の現在の AI アプリドキュメントでは、エンドポイントが /run/ai-app/{appId} の形式で示され、QUEUED、RUNNING、SUCCESS、FAILED などの状態を持つタスクオブジェクトが返されます。フィールド名については、該当する正確な API 詳細ページで生成されたリクエスト例を唯一の信頼情報源としてご利用ください。

const response = await fetch(`${RUNNINGHUB_BASE}/run/ai-app/${APP_ID}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RH_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    nodeInfoList: inputMappings,
    webhookUrl: process.env.RH_WEBHOOK_URL
  })
});

if (!response.ok) throw new Error(`Submit failed: ${response.status}`);
const task = await response.json();
```ComfyUI ワークフローでは、該当するサンプルのいずれかをインポートし、環境設定を使用しない場合にのみ `RH OpenAPI Settings` を接続して、静的値でグラフを実行します。正常に動作した後、変化させる必要のあるノード（プロンプト、参照画像／動画、再生時間、アスペクト比、出力オプションなど）のみを外部から設定可能にし、それらのノード ID をワークフローのバージョン横に記録してください。

RunningHub の Seedance 2.0 アセットツールは、さらに別の選択肢を提供します。`real_person_mode=false` とすると、直接アップロード経路が採用されます。有効化すると、選択されたローカルの画像または動画スロットが、モデルリクエストの前にアセットへ変換されます。`conversion_slots` は、どのスロットがこの処理に参加するかを制御します。9枚の画像と3本の動画を含むペイロードでは、どのマッピングが失敗を引き起こしたかが判別しづらいため、まず1枚の画像でテストを行ってください。

```official-video
src=https://r2.seedance.tv/blog/gpt-image-2-5-to-video-workflow/product-orbit-motion-v1.mp4
poster=https://r2.seedance.tv/blog/gpt-image-2-5-to-video-workflow/product-orbit-motion-poster-v1.jpg
label=API 結果の検証用：縦向き製品軌道動画

この再生可能な Seedance モーション出力は、検索後に確認すべき項目（製品の幾何学的形状の安定性、制御されたカメラ移動、クリーンなフレーム）を示しています。これは RunningHub のベンチマークとして提示されているものではありません。

API 境界を越えて存続する入力を構築する

API は、どのファイルが最初のフレームか、最後のフレームか、キャラクターリファレンスか、スタイルリファレンスかを推論できません。送信前に、入力マニフェストを作成してください。ローカル名、ソースのチェックサム、MIME タイプ、意図するスロット、作成済みの場合はアセット ID、およびそれを参照するプロンプトレーベルを格納します。これは、単に final-2.png と命名されたファイル群のフォルダーを用意するよりもはるかに有用です。

{
  "shot": "kitchen-01",
  "references": [
    {"role": "first_frame", "assetId": "asset-example-01"},
    {"role": "style", "url": "https://your-storage.example/style.jpg"}
  ],
  "prompt": "中距離トラッキングショット；シェフが料理を盛り付ける；湯気が立ち上る；温かみのある実用的な照明",
  "ratio": "16:9"
}

公式ドキュメントで説明されている ComfyUI 統合機能は、1つのアセット ID、asset://<asset_ID> 形式の値、カンマまたは改行で区切られた値、あるいは JSON 配列形式の文字列のいずれかを受け入れます。この柔軟性は便利ですが、一貫性を保つ方が安全です。コードベース内で1つの表現形式を選択し、グラフ実行前にその形式を検証してください。画像→動画変換では、統合機能が first_frame および last_frame を識別します。マルチモーダル動画ノードでは、複数の画像および動画スロットを公開できます。自動化の前にリファレンスパッケージを精緻化するには、リファレンス→動画ワークスペース をご利用ください。

プロンプトは、実行可能なショット指示として記述してください。構図、被写体、動作、環境、照明、音響をそれぞれ分離して記述します。初回の呼び出しで創造的に失敗した場合、エンドポイント、アセット、プロンプト、ワークフローを同時に変更するのではなく、1つの要素（チャンネル）だけを簡素化してください。画像→動画プロンプトワークフロー では、再利用可能なプロンプトパターンが提供されています。

この新鮮で完成度の高いフレームは、読み取り可能な手の動き、食品の幾何学的形状、湯気、実用的な照明という4つの詳細を示しており、これらは生成されたクリップ全体で確認すべき要点です。

結果のポーリング、保存、レビュー

送信後は、ポーリングを開始する前に返された taskId を永続化してください。上限付きの指数バックオフを用い、最終的な失敗時には停止し、再起動したワーカーが同一ジョブを継続できるよう、ポーリング操作は冪等性を保つように設計してください。ルートがウェブフックをサポートしている場合、ペイロードを信頼されたものとして扱う前に、その署名または共有シークレットを検証してください。コールバックは、既存のタスクレコードを更新するものであり、新たな生成を2回目に行うものではありません。

ステータスが SUCCESS の場合、MP4 を直ちにコピーしてください。RunningHub では、生成結果のリンクおよびアップロードリンクは 24 時間後に期限切れになると明記されています。そのため、人間がレビュー画面を開いた時点で初めてダウンロードするという運用は危険です。ファイル、チェックサム、プロバイダのタスク ID、プロンプトのバージョン、ソースマニフェスト、生成タイムスタンプをまとめて保存してください。その後、配信スタックで必要に応じて、プレビューポスターおよびブラウザ再生可能なプロキシを生成してください。

微細な動きのレビュー用：コーヒーと湯気のモーションクリップ

この2つ目の実際のモーション出力は、抑制された手の動き、立ち上る湯気、日差しを活用しており、レビュアーにとって製品軌道とは異なる失敗要因を提示します。

最初のフレームだけでなく、クリップ全体をレビューしてください。アイデンティティ、オブジェクトの幾何学的形状、モーションの連続性、カメラパス、背景の安定性、音響との整合性、配信安全性を評価します。技術的には成功したタスクでも、実用できない場合があります。複数のモデルやプロバイダを用いるキャンペーンでは、マルチモデル AI 動画ワークフロー が、ルートを跨いで統一されたレビュー基準を維持する方法を示しています。

生地の方向性、手の形、足の接地状態、水平線の安定性、カメラの高さ——これらは、モーション重視の結果に対する簡潔な承認チェックリストを構成します。

一般的な RunningHub Seedance 2.0 API エラーの対処

エラーはライフサイクル段階ごとに分類して対処してください。401 や 403 エラーは、キー、リージョン、メンバーシップ、権限の問題を示しており、プロンプトの問題ではありません。taskId が返される前にリクエストが拒否された場合、通常はエンドポイント、アプリ ID、コンテンツタイプ、またはリクエストボディの構造に誤りがあります。キューに登録されたタスクが一切進行しない場合は、キューまたはタイムアウトの問題です。内容検証の詳細付きで FAILED となったタスクは、より安全なプロンプトまたはリファレンスが必要です。一方、URL が期限切れとなった SUCCESS タスクは、ストレージ障害を意味します。| 症状 | 最初に確認する項目 | 対応策 | |---|---|---| | 認証エラー（Unauthorized） | キーのソースとベースリージョン | 古くなったノードオーバーライドを削除；キーをローテーションし、最小限の呼び出しで再テスト | | ノードマッピングが無効 | ワークフローのバージョンとノードID | 現在のグラフをエクスポートし、指定されたノードのみを更新 | | アセット変換に失敗 | スロット名、タイプ、およびソースのアクセス可能性 | 1つのスロットでテスト；公式ドキュメントにある直接アップロードフォールバックを使用 | | タスクがキューのまま | ポーリング間隔とアカウントキュー | リトライ間隔を空ける；重複ジョブを自動生成しない | | 結果URLが有効期限切れ | 耐久性ストレージイベント | 元のファイルが一度もコピーされていない場合にのみ再実行 | | クリップの映像が不適切 | プロンプトおよびソースマニフェスト | API仕様は変更せず、クリエイティブ変数のうち1つだけを修正 |

ステータスコード、プロバイダーのエラーコード、タスクID、ワークフローのバージョン、およびサニタイズ済みのフィールド名をログに記録してください。APIキーおよび完全なプライベートメディアURLは、絶対にログに記録してはいけません。プロバイダーのルートが冪等性キー（idempotency key）を公開していなくても、自社サービス内で必ず独自のidempotency keyを付与してください。これにより、クライアント側のリトライによる二重課金を防げます。

統合自体は技術的に動作しているものの、調整・連携がボトルネックとなっている場合は、Seedance Agent を活用して参照資料を整理し、 brief をショット単位に分解し、承認済み出力を比較し、失敗したステージのみを再実行してください。これは運用（production）層における戦略的選択であり、基盤となるAPIの理解を置き換えるものではありません。

結論

耐久性のある RunningHub Seedance 2.0 API の構築は、単一の成功した cURL コマンドではなく、ライフサイクルです。正しい AI App または ComfyUI ルートを選択し、API キーはコード外に保管し、最小限の呼び出しで動作を検証し、アセットを明示的にマッピングし、taskId を永続化し、ポーリング時はバックオフを実施し、一時的な結果は即座にコピーし、書面による受入チェックリストに基づいてクリップ全体を評価してください。これらの境界が安定したら、Webhook、より広範なマルチモーダル入力、バッチスケジューリング、人による承認といった機能を追加できますが、追加の自動化によって障害を隠さないよう注意してください。費用発生前に参照資料やショットを計画し、承認済みの成果物をレビューから選択的再実行まで一貫して継続させるには、プロジェクトを Seedance Agent で開始してください。