Seedance 2.5 API ガイド：コードや AI agent から動画を生成する

Seedance 2.5 は、テキストおよび参照素材から動画を生成できる優れたモデルです。現在のアクセスは pre-release かつ provider 経由であり、一般公開はされていません。そのため、以下の内容はすべて想定される挙動として捉え、リリース前に provider と確認してください。本記事は独立したガイドであり、EvoLink は当サイトが推奨するサードパーティ provider です（当サイトは ByteDance とは一切関係ありません）。リクエスト構造は EvoLink の API に準拠しています。本番導入前に同社のドキュメントと照合してください。

セットアップ

EvoLink で API キーを作成し、残高をチャージしてキーをエクスポートすれば、テストを開始できます。

export EVOLINK_KEY="sk-..."

課金については公開料金はまだ発表されていません。出力秒数単位での課金が見込まれ、ネイティブ音声は追加料金なしで含まれ、content_filter をオフにすると約 1.1 倍の費用になる見込みです。開発前に provider のコンソールで現行モデルをご確認ください。

生成リクエスト

モデル id は seedance-2.5-reference-to-video です（pre-release のため、provider が確定させた際に差し替えられるよう設定可能にしておいてください）。

curl -X POST https://api.evolink.ai/v1/videos/generations \
  -H "Authorization: Bearer $EVOLINK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-reference-to-video",
    "prompt": "golden-hour drone pullback over a coastal city, anamorphic flare",
    "duration": 5,
    "quality": "720p",
    "generate_audio": true,
    "content_filter": true
  }'

各フィールドの説明：

• model — 上記の pre-release 版 id。設定可能にしておいてください。
• prompt — ショットのテキスト記述。
• duration — 秒数。想定範囲は 4〜30（デフォルトは 5）。上限は provider にご確認ください。
• quality — "480p" または "720p"（デフォルトは "720p"）。1080p などのより高い解像度は provider のドキュメントで確認されるまで未確定です。対応済みと見なさないでください。
• generate_audio — ブール値、デフォルトは true。ネイティブ音声は 1 回の生成に含まれ、追加料金はかかりません。
• content_filter — ブール値、デフォルトは true。false に設定すると約 1.1 倍で課金される見込みです。
• image_urls（≤30）、video_urls（≤10）、audio_urls（≤10）— 参照ファイル。詳細は後述します。
• callback_url — 完了通知用の任意の webhook。

API はタスクを返すので、その後ポーリングを行います。

{ "id": "task_8f2c...", "status": "pending" }

パラメータの詳細は当サイトの API ページをご覧ください。

ポーリングで結果を取得する

ステータスが completed になるまで、タスク詳細エンドポイントをポーリングします。

curl "https://api.evolink.ai/v1/task-detail?id=task_8f2c..." \
  -H "Authorization: Bearer $EVOLINK_KEY"

status は pending → processing → completed（または failed）の順に遷移します。completed になったら、返された動画 URL をダウンロードしてください。

Node の例

fetch ベースの最小構成のフロー——まず送信し、次にポーリングします。

const KEY = process.env.EVOLINK_KEY;
const BASE = "https://api.evolink.ai/v1";
const MODEL = "seedance-2.5-reference-to-video"; // pre-release, keep configurable

async function generate() {
  const res = await fetch(`${BASE}/videos/generations`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: MODEL,
      prompt: "the character walks through a market at dusk",
      duration: 5,
      quality: "720p",
      generate_audio: true,
      content_filter: true,
    }),
  });
  const { id } = await res.json();
  return id;
}

async function poll(id) {
  while (true) {
    const res = await fetch(`${BASE}/task-detail?id=${id}`, {
      headers: { "Authorization": `Bearer ${KEY}` },
    });
    const task = await res.json();
    if (task.status === "completed") return task;
    if (task.status === "failed") throw new Error("generation failed");
    await new Promise((r) => setTimeout(r, 5000));
  }
}

const id = await generate();
const done = await poll(id);
console.log(done);

参照ファイル

参照素材は、タイプ別に URL リストとして添付できます。

• image_urls — 画像は最大 30 枚。
• video_urls — 動画は最大 10 本。
• audio_urls — 音声クリップは最大 10 本。

{
  "model": "seedance-2.5-reference-to-video",
  "prompt": "the character walks through the market, camera following the uploaded drone move",
  "image_urls": [
    "https://cdn.example.com/character_front.png",
    "https://cdn.example.com/character_profile.png"
  ],
  "video_urls": ["https://cdn.example.com/drone_move.mp4"],
  "audio_urls": ["https://cdn.example.com/score_draft.mp3"],
  "duration": 5,
  "quality": "720p",
  "generate_audio": true
}

画像はキャラクターの同一性と色調を固定し、動画クリップはカメラワークとモーションのスタイルを提供し、音声はテンポを駆動します。これらを活かす prompt のパターンについては、prompt ライブラリで実際のリクエストと出力をご覧いただけます。

本番環境でのコスト管理

公開料金はまだ発表されていないため、以下はあくまで方向性の目安として捉え、provider のコンソールでご確認ください。

• ドラフトは短く、完成版は長く。 課金は出力秒数単位になる見込みのため、duration が最大のコストレバーです。短いドラフトで反復してから、承認済みの長いテイクをレンダリングしてください。
• duration はサーバー側で上限を設ける。 自前の API レイヤーで duration に上限をかけ、バグがリトライループの中で長尺テイクをレンダリングし続ける事態を防いでください。想定範囲は 4〜30 秒であることをお忘れなく。
• content_filter に注意。 デフォルトはオンです。オフにすると請求額が約 10% 増える見込みです。
• 音声は無料。 ネイティブ音声は追加料金なしで含まれるため、generate_audio: true にしても秒単位の計算は変わりません。

provider が料金を公開したら、料金ページで最新の数字を再現するか、プレイグラウンドで任意の構成を試算してみてください。

AI agent への組み込み

お使いの agent フレームワーク（Claude Agent SDK、Vercel AI SDK、LangChain、あるいは MCP server）で、REST 呼び出しを 1 つの関数ツールとしてラップします。prompt、duration、quality、generate_audio、content_filter、そして参照 URL リストをパラメータとして公開してください——これは API ページの契約仕様とそのまま対応します。

本番運用での注意点を 1 つ：ポーリングステップは生成ステップとは別のツールにしてください。レンダリング中にツールスロットを占有するブロッキング呼び出しよりも、「タスク X が完了したか確認する」という形の方が、agent ははるかにスムーズに扱えます。推奨される構成は agent ガイドをご覧ください。

初日から作り込むべきエラーハンドリング

• 認証 / 残高エラー — チャージ用リンクを添えてユーザーに提示してください。むやみにリトライしてはいけません。
• レート制限 — 指数バックオフを採用してください。負荷が高いとレンダリング時間が延びることがあります。
• failed ステータスまたはコンテンツポリシーによる拒否 — 返された理由をログに記録してください。これらは通常、prompt の問題であり、通信層のバグではありません。

アクセスは pre-release のため、モデル id がまだ自分のアカウントで有効化されていないケースも処理しておきましょう——設定可能な状態を維持し、本番導入前に provider のサポート状況をご確認ください。

API キーを取得し、上記のリクエストを実行してテストを始めましょう：API クイックスタート →