開発者は今すぐ EvoLink 経由で Seedance 2.5 を使えますか？

はい。公式 API と EvoLink 統合は公開済みです。T2V、I2V、R2V の model ID を選び、EvoLink キーを作成し、短いテストから始めてください。

Seedance 2.5 の model ID はハードコードすべきですか？

設定可能に保ってください。そうすれば各リクエストが対応する workflow を選択でき、アプリケーションは Seedance 2.0 を rollback として保持できます。

ローカルモックは何をシミュレートすべきですか？

最低限、ジョブ作成、pending、processing、completed、failed、無効なリクエスト、キー欠落、レート制限、サーバー利用不可、重複ポーリング、複数回届くコールバックをシミュレートしてください。これらはレジリエンスのシナリオであり、最終的な Seedance 2.5 エラー契約についての主張ではありません。

ローカルのスキーマテストに合格すれば、統合は本番就緒と言えますか？

いいえ。ローカルテストは、アプリケーションが現在の計画上の構造とモデル化された状態遷移を扱えることを証明するだけです。本番就緒には、さらに provider の公式スキーマ、ライブ認証、課金、出力取得、遅延、失敗、品質のテストが必要です。

なぜ Seedance 2.0 をフォールバックに使うのですか？

2.5 のワークロードが品質、遅延、コストの閾値を満たさない場合の、文書化された rollback になるからです。すべての 2.5 リクエストが 2.0 で安全に表現できるわけではないため、フォールバックは適格性ベースでなければなりません。

公開済みの Seedance 2.5 ルートに対して、なぜ HTTP 503 をモックするのですか？

動画アプリケーションは provider を問わず一時的な上流の利用不可に耐えるべきで、モックならライブジョブを消費せずにその経路を安価にテストできます。このフィクスチャはレジリエンステストであり、Seedance 2.5 の作成エンドポイントがその応答を文書化している証拠ではありません。

Seedance 2.5 EvoLink API ガイド：ライブ統合チェックリスト

Seedance 2.5 公式 API と EvoLink 統合は公開済みです。いまや provider アダプターを定義し、トランスポート型を生成し、ドメインペイロードを検証し、非同期ジョブを送信し、代表的な失敗をテストし、Seedance 2.0 の rollback を保持できます。

ただし、ルートが利用できるだけではワークロードは本番就緒になりません。正しいゴールは、自分の入力に対して品質、キュー時間、課金、失敗挙動を実測したライブ統合です。

2026 年 8 月 7 日の検証スナップショット：公式開発者 API と EvoLink ルートは公開済みです。EvoLink は 3 つの workflow ID、4〜30 秒、480p/720p、R2V の参照素材上限を公開しています。トラフィックを拡大する前に、現行価格とアカウント制限を EvoLink で確認してください。Seedance25API はサイト作成のライブ統合支援を公開している独立サイトであり、ByteDance と提携関係にありません。

本ガイドが扱う範囲と、API リファレンスが扱う範囲

API クイックスタートは正確なフィールド、エンドポイント例、現在のリクエストスキーマを担当します。本ガイドは、そのスキーマを取り巻くエンジニアリングプロセスを担当します。

問い	担当ページ
今日どのライブパターンが使えるか？	API クイックスタートと現行の EvoLink documentation
agent はどのリクエスト・ポーリング構造を読み込めるか？	統合スキーマ
型付きクライアントをどう生成するか？	本ガイド
トラフィック拡大前にどうテストするか？	本ガイド
スキーマ変更にどう対応するか？	本ガイド
何が 2.0 にフォールバックできるか？	本ガイドと 2.5 vs 2.0 判断ガイド
最終的なライブ価格はいくらか？	料金ページと provider コンソール

これらの責任を分離しておくことで、Blog が documentation の古いコピーになるのを防げます。

固定された計画契約からモックと可観測性を経て、サーキットブレーカーと適格フォールバックに至る Seedance 2.5 API readiness ワークフロー

まず本番検証の境界を定義する

プロジェクトの README またはアーキテクチャ決定記録に、次の記述を書き込んでください：

Before traffic: request validation, type generation, job lifecycle,
error mapping, fallback policy, logging, and callback idempotency.

Measure on the live route: output quality, latency, reference ingestion,
callback delivery, actual cost, failure behavior, and account rate limits.

この境界は受け入れ基準を変えます。CI は有料呼び出しなしで通過すべきです。そのうえで小さな canary が、トラフィック拡大前にライブでしか検証できない挙動を確認します。

ステップ 1：統合スキーマをスナップショットしてバージョン管理する

本番ビルドのたびに、変化し続けるリモート URL からクライアントコードを生成しないでください。レビュー済みスナップショットをダウンロードまたは vendoring し、そのハッシュを記録し、意図的に更新します。

curl -fsSL https://seedance25api.io/openapi.json \
  -o contracts/seedance-2.5.openapi.json

shasum -a 256 contracts/seedance-2.5.openapi.json

統合スキーマは以下をモデル化しています：

ライブの POST /v1/videos/generations によるタスク作成；
GET /v1/tasks/{task_id} によるポーリング；
workflow 固有の必須 model と prompt；
文書化された launch フィールドと参照素材の上限；
現行の EvoLink タスク状態語彙：pending、processing、completed、failed；
ローカルのレジリエンステスト用の代表的なエラー。

EvoLink provider documentation が引き続き正です。この独立スキーマを固定することで、ライブルートとタスク取得を provider アダプターの背後に置いたまま、チームはレビュー可能な契約変更を得られます。

ステップ 2：型は生成し、ドメイン型は独立に保つ

スナップショットからトランスポート型を生成します：

npx openapi-typescript@7 contracts/seedance-2.5.openapi.json \
  -o src/generated/seedance-transport.ts

生成された型をアプリケーションのドメインモデルにしてはいけません。生成されたトランスポートコードは、契約が変わると変わります。レビュー状態、参照素材のロール、受け入れ済み出力といったプロダクト概念は、安定したアプリケーション型に属します。

export type VideoRequest = {
  prompt: string;
  durationSeconds: number;
  quality?: string;
  references: Array<{
    type: "image" | "video" | "audio";
    url: string;
    role: string;
  }>;
};

export type VideoJob = {
  id: string;
  state: "queued" | "running" | "generated" | "failed";
  outputUrl?: string;
  errorCode?: string;
};

アダプターが、安定したドメイン型を現在の provider トランスポートへマッピングします。

ステップ 3：ルートの capability は設定に置く

3 つのライブ EvoLink workflow ID を使いますが、選択した ID は UI コンポーネント、データベースレコード、テスト、ワーカーコードに撒き散らすのではなく、設定として保持します。

type RouteConfig = {
  baseUrl: string;
  model: string;
  maxDuration?: number;
  qualities?: string[];
  maxImages?: number;
  maxVideos?: number;
  maxAudio?: number;
  enabled: boolean;
};

export const seedance25: RouteConfig = {
  baseUrl: process.env.EVOLINK_BASE_URL ?? "https://api.evolink.ai/v1",
  model: process.env.SEEDANCE_25_MODEL ?? "seedance-2.5-text-to-video",
  maxDuration: Number(process.env.SEEDANCE_25_MAX_DURATION ?? 30),
  qualities: (process.env.SEEDANCE_25_QUALITIES ?? "480p,720p").split(","),
  maxImages: 30,
  maxVideos: 10,
  maxAudio: 10,
  enabled: Boolean(process.env.EVOLINK_API_KEY),
};

ルートは、人間が EVOLINK_API_KEY を供給したときにだけ実行可能になります。認証情報なしで送信できてしまうコードには起動時のアサーションを追加し、workflow 固有のフィールドを検証し、トラフィック拡大前に smoke テストを再実行してください。

ステップ 4：provider がリクエストを見る前に検証する

クライアント側のコントロールはユーザビリティを高めますが、コストと信頼性を守るのはサーバー側の検証です。

export function validateRequest(input: VideoRequest, route: RouteConfig) {
  const errors: string[] = [];

  if (!input.prompt.trim()) errors.push("prompt is required");
  if (route.maxDuration && input.durationSeconds > route.maxDuration) {
    errors.push(`duration must be at most ${route.maxDuration}`);
  }
  if (input.quality && route.qualities && !route.qualities.includes(input.quality)) {
    errors.push(`quality ${input.quality} is not enabled for this route`);
  }

  const count = (type: VideoRequest["references"][number]["type"]) =>
    input.references.filter((r) => r.type === type).length;

  if (route.maxImages && count("image") > route.maxImages) errors.push("too many image references");
  if (route.maxVideos && count("video") > route.maxVideos) errors.push("too many video references");
  if (route.maxAudio && count("audio") > route.maxAudio) errors.push("too many audio references");

  return errors;
}

URL の到達可能性、メディアのメタデータ、認可、署名付き URL の有効期限には、それぞれ独自のチェックが必要です。文字列として有効な URL でも、provider が取得する前に期限切れになり得ます。

ステップ 5：非同期ライフサイクル全体をモックする

有用なモックはステートフルです。完成した動画を即座に返すのではなく、ジョブ ID を返して状態を進めるべきです。

{
  "create": { "id": "mock-job-001", "status": "pending" },
  "poll_sequence": [
    { "id": "mock-job-001", "status": "pending", "progress": 0 },
    { "id": "mock-job-001", "status": "processing", "progress": 40 },
    {
      "id": "mock-job-001",
      "status": "completed",
      "progress": 100,
      "results": ["https://example.invalid/mock-output.mp4"]
    }
  ]
}

URL には予約済みの .invalid ドメインを使っているため、テストが誤って無関係なファイルをダウンロードすることはありません。

意味のあるすべての結果に対してフィクスチャを用意してください：

フィクスチャ	期待されるアプリケーションの挙動
`200 create`	ポーリング前に provider のジョブ ID を永続化する
`400 invalid request`	フィールド単位の修正を提示する。同じ内容で再試行しない
`401 invalid key`	停止し、キー設定の修復を人間に依頼する
`429 rate limited`	ジッター付きの上限付きバックオフを適用する
シミュレートした `503 unavailable`	ルートのサーキットを開き、フォールバック適格性を評価する
`completed`	出力、使用量、生レスポンスを保存し、人間レビューに入る
`failed`	理由を保存する。トランスポート成功として扱わない
重複コールバック	状態遷移を二重適用せずに成功を返す

アプリケーションの期限を超えて processing にとどまるジョブもシミュレートしてください。provider 側のジョブは継続しているかもしれませんが、ユーザー向けの操作には明確なタイムアウト状態と、確認を再開する手段が必要です。

ステップ 6：アダプターをスキーマテストし、次にライブルートを契約テストする

最初のスキーマテストは、アプリケーションのリクエストが固定した統合スキーマに受理されることを証明すべきです。2 番目は、すべてのタスク状態が正しくマッピングされることを証明します。3 番目は、スキーマが予期せず変わったときに失敗すべきです。契約の差異については、EvoLink provider documentation が引き続き正です。

import assert from "node:assert/strict";

const mapped = mapProviderJob({
  id: "mock-job-001",
  status: "processing",
  progress: 40,
});

assert.deepEqual(mapped, {
  id: "mock-job-001",
  state: "running",
  outputUrl: undefined,
  errorCode: undefined,
});

レビュー済みの契約スナップショットと新しく取得したコピーを比較する CI ステップを追加します。ただし、自動では上書きしません：

curl -fsSL https://seedance25api.io/openapi.json \
  -o /tmp/seedance-2.5.latest.json

diff -u contracts/seedance-2.5.openapi.json \
  /tmp/seedance-2.5.latest.json

diff はレビューのトリガーであり、破壊的変更の証明ではありません。説明文の更新は無害かもしれませんが、必須フィールド、enum、状態、レスポンスの変更は、コードとフィクスチャの更新を要するかもしれません。

ステップ 7：失敗クラスごとにリトライを設計する

「3 回リトライする」はポリシーではありません。失敗クラスごとに異なる対応が必要です。

失敗	リトライ？	ポリシー
レスポンス前のネットワークタイムアウト	場合による	冪等性の保護付きでリトライするか、再送信前に照合する
`400`	しない	リクエストを修正する
`401`	しない	シークレットまたは権限を修復する
`429`	する	provider のガイダンスに従う。指数バックオフ + ジッター
シミュレートした `503`	限定的	サーキットを開く。後でリトライするか、適格なフォールバックを使う
ジョブ `failed`	条件付き	理由が理解でき、ポリシーが許す場合のみリトライ
ポーリングのタイムアウト	する	同じジョブのポーリングを再開する。複製を作らない

provider が冪等キーを公開していない場合、アプリケーション自身の送信記録が必要です。provider がリクエストを受理した後のネットワークタイムアウトは危険です。盲目的な再送信は、課金対象のジョブを 2 つ作りかねません。

ステップ 8：フォールバックの適格性を明示する

Seedance 2.0 は今日でも周辺アプリケーションを動かせますが、フォールバックは文字列の置換ではありません。2.5 向けに計画されたリクエストは、2.0 の尺や参照素材の制約を超えているかもしれません。

function canFallbackToSeedance20(input: VideoRequest) {
  return (
    input.durationSeconds <= 15 &&
    input.references.filter((r) => r.type === "image").length <= 9 &&
    input.references.filter((r) => r.type === "video").length <= 3 &&
    input.references.filter((r) => r.type === "audio").length <= 3
  );
}

上記の制限は引用した公開 EvoLink 2.0 ガイドを反映したもので、アクティブなルートに対して引き続き確認が必要です。リクエストが適格でない場合は、ユーザーに選択肢を提示してください：短くする、参照素材を減らす、後で 2.5 ルートを再試行する、あるいは別の検証済みルートを選ぶ。サイレントな切り詰めは安全なフォールバックではありません。

ステップ 9：トラフィック拡大前に必要な証拠をログに残す

構造化フィールドを今から準備します：

internal_request_id
provider_route
model_id
contract_version
provider_job_id
submit_attempt
http_status
provider_state
duration_requested
reference_counts
created_at / completed_at
usage_or_cost
output_url_expiry
review_outcome
fallback_route

bearer トークンや機微な署名付き URL を、マスキングなしでログに残してはいけません。ログは、エラーがバリデーション、認証、キャパシティ、生成、出力取得、人間による却下のどれに由来するかに答えられるべきです。

本番トラフィック前の検証チェックリスト

契約テスト済みのソフトウェアにも、ライブの証拠が必要です。次のチェックを順に実行してください：

provider documentation で、最終的な model ID とアカウントの権限を確認する。
計画上の前提をライブの provider スキーマに置き換え、すべての差異をレビューする。
短く低リスクな smoke ジョブを作成する。
返されるすべての状態と出力アクセスを検証する。
成功時の課金記録を確認し、失敗時の課金は別途調査する。
リトライストームを起こさずに、レート制限と一時的な利用不可の処理をテストする。
コールバックを有効にする場合は、その認証、重複、順序を検証する。
凍結したワークロード評価セットを実行する。
適格なジョブの小さな canary だけを有効にする。
kill switch が検証済みルートへトラフィックを戻すことを確認する。

統合が canary の準備を満たすのは、アプリケーションの挙動と provider の挙動が一致したときだけです。より広い本番への準備を満たすのは、出力の受け入れ、コスト、遅延、エラーの閾値に合格したときだけです。

推奨される次のステップ

機械可読な統合スキーマを固定し、型を生成し、非同期状態機械をテストしてください。API クイックスタートのライブ 2.5 例と、安全なキー受け渡しのための agent ガイドを使い、Seedance 2.0 は rollback の適格性が明示された場合にのみ使います。

この作業は、最終的な Seedance 2.5 のフィールドが変わっても価値を保ちます。アダプターが変更を隔離し、ジョブ、レビュー、ログ、評価のシステムはそれを生き延びます。

出典

検証ノート：2026 年 8 月 7 日に、EvoLink の Seedance 2.5、Seedance 2.0、タスク詳細 documentation と照合しました。ローカルの OpenAPI ファイルはサイト作成の統合支援であり、現在の model ID、リクエストフィールド、制限、価格、エラー契約については、EvoLink 自身の documentation とコンソールが引き続き正です。