EvoLink 経由での Seedance 1.5 Pro API 統合ガイド：非同期タスク、コールバック、生成モードの詳細

本ガイドで学べること

• EvoLink の非同期タスク API（作成 → ステータス確認 → 結果取得）を使用した Seedance 1.5 Pro の実装。
• callback_url の安全な運用（HTTPS 限定、リトライ仕様、および失敗処理）。
• 単一のエンドポイントで テキストからビデオ (Text-to-Video)、画像からビデオ (Image-to-Video)、前後フレーム指定 (First-Last-Frame) を使い分ける方法。
• 冪等性キー (Idempotency Key) とリトライ予算による重複処理の防止。
• リンク切れ（24時間の保持期間）前に、独自のストレージへアセットを再ホストする方法。
• 不安定な価格情報に頼らずに、「成功した出力あたりのコスト」をモデル化する方法。
• Veo 3.1 や Kling O1 との統合面でのトレードオフ比較（価格ではなく、設計思想に基づいた比較）。

クイックスタート・チェックリスト（タスク管理ツールに貼り付け可能）

• POST /v1/videos/generations によるタスク作成の実装
• GET /v1/tasks/{task_id} によるポーリングの実装
• callback_url エンドポイントの実装（2xx を即時返し、非同期で処理）
• ユーザーの意図（「生成」ボタンのクリック等）ごとに冪等性キーを追加
• 24時間以内に動画アセットを再ホストする仕組みの構築
• 監視指標の設定：p50/p95 レイテンシ、ポリシーによる失敗率、リトライ率、成功までの平均試行回数

EvoLink API 仕様（開発の要点）

• タスクを作成 → task_id を受け取る
• GET /v1/tasks/{task_id} をポーリングするか、callback_url で通知を受け取る
• 完了後、results URL を取得し、即座にダウンロード/転送する（リンクに有効期限があるため）

エンドポイント概要

• POST https://api.evolink.ai/v1/videos/generations

• GET https://api.evolink.ai/v1/tasks/{task_id}

• 出力リンクの有効期限は 24時間 です。速やかに再ホストしてください。

1つのエンドポイントで3つのモード（image_urls により自動判別）

• 0 枚 → テキストからビデオ (Text-to-Video)
• 1 枚 → 画像からビデオ (Image-to-Video)
• 2 枚 → 前後フレーム指定 (1枚目を開始フレーム、2枚目を終了フレームのガイドとして使用)

• 1リクエストにつき最大 2 枚まで
• 画像1枚あたり 10MB 以下
• 対応形式：jpg/jpeg/png/webp
• URL はサーバーから直接アクセス可能であること

本番環境で重要なリクエスト項目

これらは、実際に運用を軌道に乗せるために調整が必要なパラメータです：

• model: "seedance-1.5-pro" を使用
• prompt (必須): 最大 2000 トークン
• duration: デフォルト 5秒。4〜12秒まで対応

  運用のヒント：課金は時間に比例します。時間はコスト制御の主要なレバーとして扱ってください。

• quality: 480p または 720p (デフォルト 720p)
• aspect_ratio: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, adaptive (デフォルト 16:9)
• generate_audio: boolean (デフォルト true)

  ヒント：セリフを 「二重引用符（ダブルクォーテーション）」 で囲むと、発話の精度が向上します。

• callback_url: HTTPS 限定。完了/失敗/キャンセル時の通知先（推奨）

利用シーン別の推奨パラメータ（迅速な意思決定のために）

この表は、ドキュメントや設計仕様書に引用することを想定しています。

タスクのライフサイクル：まず状態遷移を設計する

信頼性の高い統合は、予測可能な内部状態マシンから始まります：

created → queued/processing → succeeded → (ダウンロード → 再ホスト → ユーザーへ提供)
                     └──────→ failed (規約違反 | 一時的エラー | 内部エラー)
                     └──────→ cancelled

最小構成の実行例 (EvoLink)

1) タスクの作成 (cURL) — コピー＆ペースト可能

シェルでのエスケープエラーを防ぐため、単純なプロンプトを使用した例です。

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header 'Authorization: Bearer <あなたのトークン>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-1.5-pro",
    "prompt": "A detective in the rain says: \"Do not move.\" Neon reflections on the street. Subtle footsteps and radio static.",
    "duration": 8,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "callback_url": "https://your-domain.com/webhooks/evolink-task"
  }'

API は即座に以下の項目を含むタスクオブジェクトを返します：

• id (タスク ID)
• status
• usage フィールド（billing_rule, credits_reserved など）

2) タスク状態の照会 (cURL)

curl --request GET \
  --url https://api.evolink.ai/v1/tasks/<task_id> \
  --header 'Authorization: Bearer <あなたのトークン>'

完了すると、レスポンスに以下が含まれます：

• 出力 URL を含む results 配列
• status および progress (進捗)

callback_url：信頼性のためのルール（厳守）

• HTTPS 限定
• 内部ネットワーク/プライベート IP への通知は不可
• タイムアウト：10秒
• 最大 3 回のリトライ（1 / 2 / 4 秒の間隔で実行）
• コールバックのボディは、タスク照会 API のレスポンス形式に準拠

コールバック実装のチェックリスト

• 200ms〜500ms 以内に 2xx レスポンスを返す（処理は即座にキューイングし、同期的には実行しない）
• 受信した task_id が存在し、正しいユーザーのものであることを検証
• 最終状態を保存する前に、必ず GET /v1/tasks/{task_id} で最新状態を確認
• 重複通知の排除（task_id + 最終状態を保存し、重複リクエストは無視する）
• デバッグ用に生のペイロードをログ保存（秘密情報は伏字にする）
• コールバックの失敗率が上昇した際にアラートを飛ばす設定（通常、受信側の問題を示唆）

冪等性：二重処理（および「重複支払い」）の防止

サービス側が正しく動作していても、以下の理由で重複が発生する可能性があります：

• ユーザーが「生成」ボタンを連打した
• モバイルネットワークによる自動リトライ
• ゲートウェイのタイムアウト

• クライアント側で、ユーザーの1回の操作につき1つの idempotency_key を生成
• サーバー側で (user_id, idempotency_key) → task_id の対応を TTL 付きで保存
• 重複するリクエストに対しては、新しいタスクを作成せず、保存されている task_id を返す

API 側で明示的に対応している場合を除き、冪等性が自動で保証されているとは考えないでください。アプリケーションの入り口で実装してください。

アセットのデリバリ：24時間の罠

出力リンクは24時間で失効するため、以下のパイプラインを構築してください：

• status=completed になったら、直ちに結果をダウンロードする
• 独自のオブジェクトストレージ (S3/GCS/R2 等) に再保存する
• CDN を通じてユーザーへ提供する
• メタデータ（task_id、プロンプトのハッシュ、ユーザー ID、生成設定、モデレーション結果など）を永続化する

完了時の即座な再ホストにより、これを防ぎます。

経済モデルの構築（固定価格に依存しない手法）

価格が変動したとしても、長期的に機能するユニットエコノミクスモデルが必要です。

1) 課金要因を把握する

運用上、コストを左右するのは以下の要素です：

• duration (動画が長いほど高価)
• generate_audio (音声付与による追加コスト)
• 試行回数 (ユーザーが1回で満足することは稀です)

2) 「1回の試行」ではなく「1件の成功」あたりのコストを計算する

以下の数値を追跡します：

• attempts_per_success (成功1件あたりの平均試行数)
• retry_rate (リトライ率)
• policy_failure_rate (ポリシー違反による失敗率)
• p95_latency (レイテンシ)

真の原価：

セッションあたりの成功数 × 成功に必要な平均試行回数

3) 下書き → 承認 → 最終化（最も確実なコスト削減策）

試行回数が多いことが予想される場合：

• まずは安価な設定（低画質/短時間）や安価なモデルでプレビューを作成
• ユーザーが決めたものに対してのみ、Seedance 1.5 Pro（音声あり）で最終生成を実行

本番運用の落とし穴と対策

1) 非同期の罠（タイムアウトとゾンビジョブ）

• ジョブに有効期限 (TTL) を設け、UI 上で「処理中」の状態を表示し続ける
• p95 の完了時間を監視し、遅延が発生した際に適切な案内を出す

2) モデレーション結果の遅延

生成後に内容不適切と判断されるケースを想定した UI を設計してください。

• 失敗理由の分類：ポリシー違反、一時的エラー、システムエラー
• ポリシー違反に対しては、絶対に自動リトライを行わない
• プロンプトの修正案（センシティブな内容の回避など）を提示する

比較：Seedance 1.5 Pro vs Veo 3.1 vs Kling O1（設計思想・エコシステム）

価格は変化します。製品の寿命に影響する、構造的な違いを比較しましょう。

表 A — 統合と計上の設計

表 B — 本番採用のための判定マトリクス

意思決定のチェックリスト（採用の可否）

• ネイティブな音声が必要であり、プロンプトの引用符で台詞を指定できる
• 1つの契約で文生ビデオ、図生ビデオ、前後フレーム指定を使い分けたい
• 生成完了から24時間以内に独自ストレージへの転送を自動化できる

• 動画の長さベースの予算管理を好み、Google クラウドのエコシステムに馴染んでいる

• 既存映像の編集やスタイル変更がサービスの中核であり、安定したアクセス経路を確保できている

よくある質問 (FAQ)

Q: EvoLink で文生ビデオと図生ビデオを切り替えるには？

Q: Webhook とポーリング、どちらが安全ですか？

Q: なぜアセットを再ホストしなければならないのですか？

出力リンクは24時間で無効になるため、ご自身のストレージへ移す必要があります。

Q: 冪等性を確保するには？

Seedance 1.5 Pro で開発を始めましょう

仕様とトレードオフは理解できました。 次は、これをあなたの本番機能に変える番です。

• Seedance 1.5 Pro, Veo 3.1, Kling などを 1つの API キー で利用可能
• 明確なリトライ仕様を備えた 非同期タスク ＋ コールバック 通知
• 透明性の高いクレジット制による 従量課金

ほとんどのチームが1時間以内に統合を完了させています。