テキストから動画チーム向け Seedance API 本番運用チェックリスト

Seedance API のプロトタイプは、1回の動画生成が成功しただけで完成したように見えることがあります。ですが、本番環境での統合が完成するのは、システムが遅いジョブ、重複イベント、変更されるモデルルート、部分的な失敗、そして不確実なコストに耐えられるようになってからです。

この違いが重要なのは、動画生成が通常のリクエスト・レスポンス機能ではないからです。アプリケーションは処理を送信し、待機し、ステータス変更を受け取り、大きな出力を保存し、失敗を再試行すべきかどうかを判断します。モデル呼び出しは、より長いワークフローの中の1段階にすぎません。

このチェックリストは、そのワークフローを、製品、プラットフォーム、財務の各チームが一緒にレビューできる本番運用の契約へと変えます。

現在のルートに関する注意: このガイドを2026年7月27日（月）に確認した時点で、Flatkey の公開モデルカタログにはテキストから動画および画像から動画向けの seedance-2.5、さらに画像から動画向けの seedance-2.0-i2v が掲載されていました。これらの名称は恒久的な定数ではなく、カタログ上の状態として扱ってください。出荷前や許可リストを変更する前に、現在の Flatkey モデルディレクトリ を確認してください。

短い答え

ユーザー向けリクエストを動画プロバイダーの呼び出しに直接つなげないでください。両者の間に耐久性のあるジョブ層を置いてください。

本番環境での最小経路は次のとおりです:

1. ユーザーの生成リクエストを受け付けて検証する
2. 独自の冪等キーとジョブ ID を割り当てる
3. モデルルートを呼び出す前にリクエストを保存する
4. サーバーサイドのアダプター経由でジョブを送信する
5. Webhook とポーリングによる更新を冪等に処理する
6. 完了したメディアを自社で管理するストレージへコピーする
7. レイテンシ、失敗理由、モデルルート、推定コストを記録する
8. プロバイダーの文言に依存しない安定した製品ステータスを公開する

これらの手順のうち1つでも欠けると、統合はデモではうまく見えても、安全に運用するのが難しくなります。

Seedance API の本番運用が異なる理由

テキスト生成は、多くの場合、1回の HTTP 交換で有用な応答を返します。動画生成は通常、分散バッチジョブのように動作します。ユーザーの操作は、アプリケーションのリクエスト、デプロイ、ブラウザーセッション、あるいは最終的に結果を保持する一時 URL よりも長く生きることがあります。

その実際の影響は、見積もりが甘くなりがちです:

目的はプロバイダーを隠すことではありません。プロバイダー固有の挙動が、あなたの製品における恒久的な契約になってしまうのを防ぐことです。

1. ペイロードの前に製品契約を固定する

まずは、今日利用できるプロバイダーのフィールドではなく、ユーザーに約束する体験から始めます。

以下を定義します:

• 受け付ける入力タイプ: テキストのみ、画像＋テキスト、またはその両方
• 対応するアスペクト比と長さの範囲
• 最大アップロードサイズと受け付けるメディア形式
• 送信前のモデレーションと権利確認
• 想定されるステータス更新とキャンセル時の挙動
• 出力の保持期間
• 失敗したジョブがユーザーのクレジットを消費するかどうか
• 製品上で「retry」が何を意味するか

そのうえで、この契約をアダプター内で現在の Seedance ルートに変換します。

この分離は、2 つのよくある失敗モードからあなたを守ります。第 1 に、ルート更新によってパラメーターが追加・変更されても、フロントエンドを書き直す必要がなくなります。第 2 に、見込みのないジョブにお金を使う前に、アプリケーション側で未対応の組み合わせを拒否できます。

2. 独自のジョブ ID と冪等性キーを使う

すべてのリクエストには 2 つの識別子が必要です:

• 製品のジョブ ID: システム全体で表示される安定した識別子
• 冪等性キー: 誤って重複送信するのを防ぐために使う識別子

プロバイダーのタスク ID を主キーとして使ってはいけません。それは送信後にならないと存在せず、別のルートで意図的に再送信した場合は変わる可能性があります。

シンプルなリクエストレコードは次のようになります:

type VideoJob = {
  id: string;
  idempotencyKey: string;
  accountId: string;
  requestedModel: string;
  resolvedModel: string | null;
  providerTaskId: string | null;
  status: "accepted" | "queued" | "running" | "succeeded" | "failed" | "cancelled";
  attempt: number;
  outputUrl: string | null;
  failureCode: string | null;
  createdAt: string;
  updatedAt: string;
};

このレコードは外部 API 呼び出しの前に作成します。送信後、レスポンスを保存する前にアプリケーションがクラッシュした場合でも、冪等性キーがあれば、やみくもにもう 1 回生成料金を請求する代わりに突き合わせできます。

3. Seedance を 1 つのサーバーサイドアダプターの背後に置く

プロバイダー固有のリクエスト構築は 1 つのモジュールにまとめてください。製品の他の部分は、次のような正規化されたコマンドを送るだけにします。

type GenerateVideoCommand = {
  prompt: string;
  sourceImageUrl?: string;
  aspectRatio: "16:9" | "9:16" | "1:1";
  durationSeconds: number;
  qualityProfile: "draft" | "standard" | "high";
};

アダプターは次の責務を担います。

• qualityProfile を、現在利用可能なモデルと設定に解決する
• 認証をサーバー側で付与する
• アスペクト比と尺の選択を、現在の API スキーマに変換する
• タスクを送信する
• プロバイダーのエラーを正規化する
• プロバイダーのタスク ID を保存する
• コストと信頼性分析に十分なメタデータを報告する

Flatkey は、チームに 1 つの API キー、安定したルーターエンドポイント、共有バランス、そしてモデルファミリー全体での一元化された利用可視性を提供します。このアクセスレイヤーをすでに使っているチームでは、Seedance 固有の非同期ロジックはコードベース全体にルート前提を散らすのではなく、アダプター内に置いてください。Seedance API チーム向けの安定した OpenAI 互換ベース URL に関する前回のガイドでは、その境界をより詳しく説明しています。

4. ワークフローを状態機械としてモデル化する

任意のステータス文字列が製品ロジックに流れ込まないようにしてください。正規化します。

stateDiagram-v2
    [*] --> accepted
    accepted --> queued: submit accepted
    accepted --> failed: validation or submit error
    queued --> running: provider starts work
    queued --> failed: terminal provider error
    running --> succeeded: output verified
    running --> failed: terminal provider error
    accepted --> cancelled: cancelled before submit
    queued --> cancelled: cancellation confirmed
    succeeded --> [*]
    failed --> [*]
    cancelled --> [*]

明示的な復旧プロセスを実行している場合を除き、前方向への遷移のみを許可してください。遅れて届いた running イベントが、すでに succeeded とマークされたジョブを上書きしてはいけません。重複した succeeded の webhook が、2 回の保存コピーや 2 回の顧客通知を引き起こしてはいけません。

デバッグ用に生のプロバイダーイベントは別に保存し、製品上の判断は正規化された状態から行ってください。

5. Webhook と polling を併用する

Webhook は効率的ですが、アプリケーションがすべてのイベントを 1 回ずつ順序通りに処理することを保証するものではありません。Polling は遅いですが、再同期には有用です。

両方を使ってください。

• webhook path: 低遅延のステータス更新
• polling path: しばらく変更のないジョブのための定期的な復旧

Webhook ハンドラーは次を行うべきです。

1. アクティブな API が検証をサポートしている場合は、コールバックを認証する
2. インラインで重い処理をせずにイベントを解析する
3. イベントのフィンガープリントを重複排除テーブルに書き込む
4. 処理をキューに入れる
5. すばやく成功を返す

再同期ワーカーは、妥当な遅延の後もまだ終端状態ではないジョブだけを polling してください。デプロイによって同時刻に何千件ものステータス確認が発生しないよう、ジッターを追加してください。

プロバイダー固有の webhook と query フィールドは変更される場合があります。実装時には、古いブログ記事のペイロードを流用するのではなく、最新の公式 API リファレンスで必ず確認してください。

6. 障害クラスごとにリトライ可否を判断する

「失敗したジョブを再試行する」はポリシーではありません。コストリスクです。

エラーをクラス分けします：

最後の区別は特に重要です。動画は正常に生成されたのに保存先へのコピーが失敗した場合、再生成すると不要なコストが発生し、結果が変わる可能性もあります。

ジョブごとにリトライ予算を設定します。妥当なポリシーとしては、生成の送信よりもステータス確認や保存先コピーの試行を多く許可することが考えられます。

7. 出力を自分で管理するストレージへコピーする

プロバイダーがホストする結果 URL は、永続的なプロダクト資産ではなく転送先として扱ってください。

ジョブが成功したら、次の手順を実行します：

1. レスポンスに期待するメディアタイプが含まれていることを確認する
2. サイズと時間の制限付きでダウンロードする
3. ファイルが空でないこと、または明らかに途中で切れていないことを検証する
4. チェックサムを計算する
5. オブジェクトストレージへコピーする
6. 再生時間、寸法、コーデック、サイズを保存する
7. 永続コピーが利用可能になってから、プロダクトジョブを succeeded に切り替える

コピーが完了する前に、ユーザーが元のプロバイダー資産をダウンロードできるようにする場合は、それを別の一時的な状態として表現してください。永続性があるかのように、黙って約束してはいけません。

8. 機能公開前にコスト制御を追加する

動画ジョブは十分に高コストであるため、公開前にプロダクトの制限を設けるべきです。

少なくとも、次を定義してください：

• キーごと、またはチームごとの支出上限
• アプリケーションキーに対するモデルの allowlist
• アカウントごとの最大同時ジョブ数
• プランごとの最大再生時間と品質プロファイル
• 新規または信頼されていないアカウント向けの日次送信上限
• 失敗率または成功1件あたりのコストが上昇したときのサーキットブレーカー

Flatkey の公開ドキュメントでは、キーごとの上限、任意のモデル allowlist、Usage & Logs または ledger API による使用状況の可視化が説明されています。これらの制御をアクセス層のガードレールとして使い、そのうえで自社のプランと不正利用リスクに基づいてプロダクトレベルのクォータを追加してください。

新しいルートを有効化する前に、現在のカタログと Flatkey の価格を比較してください。この記事内の数値価格をアプリケーションロジックに埋め込まないでください。価格とルートの可用性は更新可能なデータです。

9. API レイテンシだけでなく、ジョブ全体を測定する

非同期の Seedance API ワークフローでは、送信が成功しても顧客体験が悪くなることがあります。

少なくとも次を追跡してください:

• 送信受理率
• キュー待ち時間
• 生成時間
• 永続出力までの総時間
• 解決済みモデルごとの成功率
• 正規化された失敗クラスごとの失敗率
• Webhook 配信遅延
• ポーリング回復率
• ストレージコピー失敗率
• 送信ジョブあたりのコスト
• 成功した永続出力あたりのコスト
• 重複送信防止件数

平均だけでなく、パーセンタイルも使用してください。中央値の生成時間は健全に見えても、最も遅い 10% のジョブがサポートチケットの大半を生み出すことがあります。

また、requestedModel と resolvedModel を別々に記録してください。そうすることでルート変更が可視化され、ロールバック判断の根拠も得られます。

10. モデル変更はマイグレーションとしてリリースする

カタログ変更は単なる文字列置換ではありません。依存関係のアップグレードとして扱ってください。

本番トラフィックを新しい Seedance ルートへ移す前に:

1. ライブのモデルディレクトリで現在のルートを確認する
2. 対応入力と出力制約を比較する
3. よく使うプロンプト種別全体で固定の評価セットを実行する
4. 成功率、レイテンシ、出力 स्वीकार率、コストを比較する
5. Webhook、ポーリング、エラー正規化をテストする
6. 少量のトラフィックでカナリアリリースする
7. カナリアが安定するまでロールバック用ルートを保持する
8. モデルの許可リストと運用ランブックを更新する

アプリケーションが「品質」設定を公開している場合は、永続的なモデル ID ではなく機能プロファイルにマッピングしてください。そうすれば、製品 API を壊さずにバックエンドのルートを変更できます。

本番対応チェックリスト

このリストをリリースゲートとして使用してください。

リクエストとアクセス

• [ ] API キーはサーバー側に保持されている
• [ ] アプリケーションキーに支出上限とモデル許可リストがある
• [ ] すべてのリクエストに内部ジョブ ID と冪等性キーがある
• [ ] 送信前に入力が検証される
• [ ] 現在の Seedance モデルルートがライブカタログで確認されている

非同期実行

• [ ] プロバイダー固有のロジックは 1 つのアダプターに集約されている
• [ ] 製品ステータスは正規化された状態マシンを使用している
• [ ] Webhook イベントは対応時に認証され、重複排除される
• [ ] ポーリングが古い非終端ジョブを再整合する
• [ ] 遅延または重複イベントが終端状態を巻き戻せない

信頼性とコスト

• [ ] リトライ動作は失敗クラスごとに異なる
• [ ] 生成リトライには厳格な上限がある
• [ ] 出力コピーのリトライで成功済み動画は再生成しない
• [ ] 同時実行数と 1 日あたりのジョブ上限が強制される
• [ ] サーキットブレーカーで劣化したルートを停止できる

出力と可観測性

• [ ] 成功したメディアが管理されたストレージにコピーされている
• [ ] 出力メタデータとチェックサムが保存されている
• [ ] 要求されたモデルIDと解決されたモデルIDがログに記録されている
• [ ] 成功した永続出力あたりのコストが測定されている
• [ ] オペレーターが停止、失敗、重複したジョブのためのランブックを持っている

Flatkey の適用範囲

Flatkey は、非同期の動画ジョブ層の必要性をなくすものではありません。その層の周辺にあるアクセスとガバナンスの作業を減らします。つまり、1つのアカウント、1つの残高、API キー制御、安定したルーター表面、ライブなモデルカタログ、そして一元化された使用記録です。

最初の統合では、より広い テキストから動画プロダクトチーム向け Seedance API クイックスタート から始めてください。機能が本番に向かう段階では、このチェックリストを、モデル呼び出しの周辺にあるキュー、状態、リトライ、ストレージ、可観測性の各層に適用してください。

チームが、現在のどのルートと使用制御が展開に適しているかを判断している場合は、本番構成を承認する前に ライブモデル と 価格 を確認してください。

よくある質問

Seedance API は同期ですか、それとも非同期ですか?

動画生成は非同期ジョブとして扱ってください。プロダクトは作業を送信し、自身のジョブ ID を返し、現在の API リファレンスに従って webhook および/またはポーリングを通じてステータス更新を処理する必要があります。

プロバイダーのタスク ID をデータベースの主キーとして使うべきですか?

いいえ。送信前に、独自の安定したジョブ ID を作成してください。プロバイダーのタスク ID は外部参照として保存し、製品識別子を変更せずに突合、再送信、またはルート変更ができるようにします。

webhook と polling の両方が必要ですか?

堅牢な本番システムでは、はい。webhook は迅速な更新を提供し、polling はイベントが遅延した、見逃した、または処理されなかったジョブを回復します。

失敗した Seedance ジョブを再試行して安全なのはいつですか?

失敗を分類した後にのみ再試行してください。容量やネットワークの失敗は再試行可能な場合があります。検証、認証、安全性、その他の終端失敗は、通常、設定変更またはユーザー側の変更が必要です。送信がタイムアウトした場合は、別の有償ジョブを送る前に、冪等性キーで突合してください。

生成された動画は自分で保存すべきですか?

はい。完了した出力を自分で管理するストレージにコピーし、ファイルを検証し、そのメタデータを保存してください。プロバイダーがホストする結果 URL は、現在の利用規約がその動作を明示的に保証していない限り、永続的な製品ストレージとして扱うべきではありません。

新しい Seedance モデルのバージョンはどのように扱うべきですか?

マイグレーションとして扱ってください。現在のカタログを確認し、固定の評価セットを実行し、品質、レイテンシー、失敗、コストを比較し、カナリアトラフィックを流し、変更が安定するまでロールバック経路を保持します。

どの Seedance モデルをハードコードすべきですか?

静的な記事をもとにモデルを恒久的にハードコードすることは避けてください。製品の機能プロファイルを、現在の Flatkey model directory に掲載されているモデルへ解決し、選択したルートは設定として保持して、運用担当者が安全に変更できるようにします。