Seedance 動画生成 — POST /v1/videos

POST /v1/videos を使用して、非同期の Seedance 動画生成タスクを作成します。タスクが完了するまでポーリングし、返された Flatkey URL から動画をダウンロードします。対応モデルは seedance-2.0、seedance-2.0-fast、seedance-2.0-mini、seedance-2.5 です。利用可否はアカウントによって異なります。現在のモデル一覧を取得するには GET /v1/models を使用してください。

エンドポイント

POST https://router.flatkey.ai/v1/videos

Flatkey は POST /v1/video/generations および GET /v1/video/generations/{task_id} も受け付けます。標準的なレスポンス構造とネイティブの usage データを使用するには /v1/videos を使用してください。

リクエスト

ヘッダー

ヘッダー	値
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

ボディパラメーター

string

必須

Seedance モデル ID: "seedance-2.0"、"seedance-2.0-fast"、"seedance-2.0-mini"、または "seedance-2.5"。

array

必須

マルチモーダル入力アイテム。空でないテキスト、画像、動画、または音声のアイテムを少なくとも 1 つ含めてください。content アイテムを参照してください。

string

出力解像度。デフォルト: "720p"。

モデル	対応する値
`seedance-2.0`	`"480p"`、`"720p"`、`"1080p"`、`"4k"`
`seedance-2.0-fast`、`seedance-2.0-mini`	`"480p"`、`"720p"`
`seedance-2.5`	`"480p"`、`"720p"`、`"1080p"`

string

出力アスペクト比: "16:9"、"4:3"、"1:1"、"3:4"、"9:16"、"21:9"、または "adaptive"。デフォルト: "adaptive"。"adaptive" の場合、モデルは入力した画像または動画に基づいてアスペクト比を選択します。seedance-2.5 では、最初のフレームを指定するタスクと、最初と最後のフレームを指定するタスクは "adaptive" のみに対応しています。

integer

動画の長さ（秒）。デフォルト: 5。Seedance 2.0 系モデルは 4〜15、seedance-2.5 は 4〜30 を受け付けます。

duration には必ず正の値を指定してください。Flatkey は Seedance を秒単位で課金するため、-1（長さをモデルに任せる）は video_price_not_configured で拒否されます。唯一の例外は seedance-2.5 の動画編集で、この場合は -1 が必須です。

boolean

右下隅に「AI generated」のウォーターマークを追加します。デフォルト: false。

boolean

同期されたモノラル音声トラックを生成します。デフォルト: true。動画だけが必要な場合は false に設定してください。生成された音声は、まれに著作権チェックに通らないことがあります。

boolean

生成された動画の最後のフレームを画像として返します。デフォルト: false。true の場合、完了したタスクに metadata.last_frame_url が含まれます。この URL からは、動画と同じサイズでウォーターマークのない JPEG をダウンロードできます。次のタスクの first_frame として使用すると、クリップをつなげられます。metadata.url と同様に認証ヘッダーは不要なため、非公開として扱ってください。

string

seedance-2.5 のみ。生成される動画のコンテナ形式: "mp4" または "mov"。デフォルト: "mp4"。MOV はカラーグレーディングや合成に向けてより高い色精度を保持します（H.264、YUV 4:4:4、PCM 音声）が、一部のプレーヤーでは開けません。MOV の結果に対しては、コンテンツエンドポイントが video/quicktime を返します。

string

seedance-2.5 の参照モードのタスクのみ。意図するタスクの種類をモデルに伝えます: "auto"（デフォルト）、"reference"、"edit"、または "extend"。明示的に指定すると、タスク種類のチェックが送信時に行われるため、無効な組み合わせはタスクの開始後ではなく即座にエラーになります。"reference"、"edit"、"extend" はいずれも content に参照アイテムが必要で、テキストのみのリクエストで "reference" を指定すると拒否されます。動画の編集と延長を参照してください。

integer

キューの優先度（0〜9）。デフォルト: 0。値が大きいほど、同じモデルで待機している優先度の低いタスクより先に処理されます。すべての Seedance 2.0 系モデルと seedance-2.5 で対応しています。0〜9 の範囲外の値は 400 で拒否されます。

integer

タスクが期限切れになるまでに待機および実行できる秒数。デフォルト: 172800（48 時間）。遅れて届いた結果が役に立たない場合は、より短い値を指定してください。

string

タスクのステータスが変わるたびに POST を受け取る公開 HTTPS URL。タスクコールバックを参照してください。https を使用し、ユーザー認証情報を含まず、2,048 文字以内で、公開アドレスに解決される必要があります。条件を満たさない場合、リクエストは 400 で拒否されます。

`content` アイテム

`type`	値フィールド	対応 `role`	制限
`text`	`text`	—	プロンプトテキスト。英語で約 1,000 語以内に収めてください。
`image_url`	`image_url.url`	`first_frame`、`last_frame`、`reference_image`	参照画像は最大 9 枚（`seedance-2.5` は 30 枚）。JPEG、PNG、WebP、BMP、TIFF、GIF、HEIC、または HEIF。30 MB 未満。各辺 300〜6000 px。アスペクト比 0.4〜2.5。
`video_url`	`video_url.url`	`reference_video`	最大 3 本、各 2〜15 秒、合計 15 秒まで（`seedance-2.5` は 10 本、合計 30 秒まで）。MP4 または MOV。200 MB 未満。総ピクセル数は約 409,600 以上（例: 854×480）。
`audio_url`	`audio_url.url`	`reference_audio`	最大 3 クリップ、各 2〜15 秒、合計 15 秒まで（`seedance-2.5` は 10 クリップ、合計 30 秒まで）。WAV または MP3。15 MB 未満。Seedance 2.0 系モデルでは、音声と一緒に画像または動画が少なくとも 1 つ必要です。

各 URL には、公開 HTTPS URL、data:<mime>;base64, 形式のデータ URI（画像と音声のみ）、またはアセットライブラリの asset:// 参照を指定できます。リクエストボディ全体は 64 MB 未満に収める必要があります。タスクごとに入力モードを 1 つ選択してください。これらのモードは混在できません:

モード	`content` の構成方法
最初のフレーム	`role: "first_frame"` の画像 1 枚。
最初と最後のフレーム	画像 2 枚（`role: "first_frame"` と `role: "last_frame"` を 1 枚ずつ）。`last_frame` には必ず `first_frame` が必要で、どちらも参照アイテムと組み合わせることはできません。
参照	`reference_image`、`reference_video`、`reference_audio` アイテムの任意の組み合わせ。

動画編集

seedance-2.5 は、参照モードで既存の動画を編集または延長できます。プロンプトで変更内容を説明し、動画を @Video1 として参照してください。

タスク	必須の設定	出力の長さ
編集（被写体の置き換え、オブジェクトの追加・削除、音声の変更）	長さ 4〜30 秒の `reference_video` を少なくとも 1 つ、`ratio: "adaptive"`、`duration: -1`。推奨: `omni_reference_task_type: "edit"`。	編集元の入力動画と同じ
延長（動画を前方または後方に続ける）	`reference_video` を少なくとも 1 つ、`ratio: "adaptive"`、正の `duration`。推奨: `omni_reference_task_type: "extend"`。	`duration`

{
  "model": "seedance-2.5",
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": -1,
  "omni_reference_task_type": "edit",
  "content": [
    { "type": "text", "text": "Edit @Video1: make the ball bright green and keep everything else unchanged." },
    { "type": "video_url", "video_url": { "url": "https://example.com/input.mp4" }, "role": "reference_video" }
  ]
}

参照動画を含むすべての seedance-2.5 リクエストと同様に、編集は入力や出力の長さに関係なく、その解像度の動画入力ありの料金で一律 30 秒分として課金されます。

ドラフトモード

seedance-2.5 では、まず低コストの 480p ドラフトを生成し、最終動画の料金を支払う前にシーン、ショット、動きを確認できます。リクエストは 2 回必要です:

ドラフトを作成する。 "draft": true と "resolution": "480p" を指定して、通常のリクエストを送信します。通常の 480p 動画として課金されます。
最終動画を生成する。 ドラフトの完了後、ドラフトのタスク ID を指す draft_task だけを content アイテムとして含め、"resolution": "1080p" を指定したリクエストを送信します。

{
  "model": "seedance-2.5",
  "resolution": "1080p",
  "content": [
    { "type": "draft_task", "draft_task": { "id": "task_3f9a00000000000000000000000000e2" } }
  ]
}

最終動画は、ドラフトのプロンプト、メディア、長さ、アスペクト比、シード、音声設定、タスクの種類を引き継ぎます。draft_task と一緒に duration、ratio、frames、seed、generate_audio、omni_reference_task_type、draft、またはその他の content アイテムを送信しないでください。送信するとリクエストは 400 で拒否されます。return_last_frame、output_format、watermark、priority、execution_expires_after、callback_url は引き続き指定できます。

ルール	詳細
モデル	`model` はドラフトと一致している必要があります。
ドラフトのタスク ID	Flatkey がドラフトに対して返した `task_…` ID を使用してください。自分のタスクであり、かつ完了している必要があります。
解像度	ドラフト: `480p` のみ。最終動画: `1080p` のみ。
有効期限	ドラフトは作成から 7 日間使用できます。
課金	最終動画は、ドラフトの長さに対して 1080p の料金で課金されます。ドラフトで参照動画を使用した場合は、動画入力ありの料金で一律 30 秒分として課金されます。

Seedance は、実在の人物の顔が写った画像や動画を直接受け付けません。実在人物アセットとしてアップロードし、asset:// で参照してください。

リクエスト例

import os
import requests

response = requests.post(
    "https://router.flatkey.ai/v1/videos",
    headers={
        "Authorization": f"Bearer {os.environ['FLATKEY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2.0",
        "content": [
            {
                "type": "text",
                "text": "An astronaut walking on the moon, cinematic lighting, slow camera push-in",
            }
        ],
        "resolution": "1080p",
        "ratio": "16:9",
        "duration": 5,
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://router.flatkey.ai/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FLATKEY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-2.0",
    content: [
      {
        type: "text",
        text: "An astronaut walking on the moon, cinematic lighting, slow camera push-in",
      },
    ],
    resolution: "1080p",
    ratio: "16:9",
    duration: 5,
  }),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

curl https://router.flatkey.ai/v1/videos \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      {
        "type": "text",
        "text": "An astronaut walking on the moon, cinematic lighting, slow camera push-in"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }'

最初と最後のフレームの入力

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "The camera slowly moves forward" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first.jpg" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/last.jpg" },
      "role": "last_frame"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false
}

マルチモーダル参照

{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "A woman smiles at the camera during a beach sunset" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/reference.jpg" },
      "role": "reference_image"
    }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "watermark": false
}

レスポンス

{
  "id": "task_3f9a00000000000000000000000000e2",
  "task_id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "model": "seedance-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1780306574
}

レスポンスフィールド

string

タスクのポーリングと完成した動画のダウンロードに使用するパブリックタスク ID。task_id も同じ値を持ちます。

string

タスクのステータス: queued、in_progress、completed、または failed。

integer

生成の進捗（0〜100）。

integer

タスク作成の Unix タイムスタンプ。

タスクステータスのポーリング

GET https://router.flatkey.ai/v1/videos/{task_id}

curl https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2 \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

生成中は、レスポンスに現在の進捗が含まれます:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "in_progress",
  "progress": 50,
  "model": "seedance-2.0",
  "created_at": 1780306574
}

タスクが完了すると、レスポンスに動画 URL とトークン使用量が含まれます:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content",
    "last_frame_url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/last-frame"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

失敗したタスクは、タスクレスポンスにエラーの詳細を返します:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "failed",
  "error": {
    "message": "The video generation task failed.",
    "code": ""
  }
}

事前に消費された残高は自動的に返金されます。

ステータスの値

ステータス	意味
`queued`	タスクは開始待ちです。
`in_progress`	動画を生成中です。`progress` は 0〜100 の範囲です。
`completed`	動画は `metadata.url` で準備完了です。トークン使用量は `usage` で確認できます。
`failed`	生成に失敗しました。詳細は `error.message` で確認でき、事前に消費された残高は返金されます。

タスクコールバック

callback_url を設定すると、ポーリングの代わりに、またはポーリングと併用して、ステータスの変化を受け取れます。タスクが in_progress、completed、または failed に移行すると、Flatkey は Content-Type: application/json で POST を送信します。ボディは、その時点で GET /v1/videos/{task_id} が返す内容とまったく同じで、完了したタスクでは metadata.url と metadata.last_frame_url を含みます。

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}

ヘッダー	値
`X-Flatkey-Event-Id`	`<task_id>:<status>`（例: `task_3f9a…e2:completed`）。同じイベントが複数回配信されることがあるため、このヘッダーを使って重複を無視してください。

5 秒以内に任意の 2xx ステータスで応答してください。そうでない場合、Flatkey は 2 秒後と 8 秒後の計 2 回リトライし、その後は送信を停止します。リダイレクトには従いません。コールバックには署名がないため、結果に基づいて処理する前にタスクをポーリングして確認してください。コールバックが失われる場合に備えて、ポーリングを信頼できる情報源として使い続けてください。

動画のダウンロード

GET https://router.flatkey.ai/v1/videos/{task_id}/content

curl -L "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content" \
  -o output.mp4

コンテンツエンドポイントは video/mp4 データをストリーミングします（タスクで output_format: "mov" を使用した場合は video/quicktime）。Bearer トークンは不要で、<video> ソースとして直接使用できます。

コンテンツエンドポイントはタスクの完了後にのみ機能し、クライアント IP によるレート制限があります。URL を持つ誰もが動画をダウンロードできるため、URL を機密情報として扱ってください。

エラー

リクエスト時のエラーは Flatkey の標準エラーエンベロープを使用します:

{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}

シナリオ	動作
`content` が空	リクエストは拒否されます。空でないテキスト、画像、または動画を含めてください。
利用不可のモデル	要求された `model` はこのルートで有効になっていません。
残高不足	タスクは作成されません。
`priority` が 0〜9 の範囲外	リクエストは `400` と `invalid_request` を返します。
無効な `callback_url`	URL が HTTPS でない、認証情報を含む、2,048 文字を超える、またはプライベートアドレスやローカルアドレスを指している場合、リクエストは `400` と `invalid_request` を返します。
`seedance-2.5` の動画編集以外での `duration: -1`	リクエストは `400` と `video_price_not_configured` を返します。
モデルに対して無効な入力	リクエストは `400` と `fail_to_fetch_task` を返します。`asset://` 参照を使用するリクエストでは、タスクが `task preparation failed` で失敗します。上記の解像度、長さ、コンテンツの制限、入力モードのルールを確認してください。料金は発生しません。
一時的なサービス障害	通常のバックオフポリシーを使用して後でリトライしてください。

エンドツーエンドの例

この例では、タスクを作成し、5 秒ごとにポーリングして、完成した動画をダウンロードします。jq が必要です。

#!/usr/bin/env bash
set -euo pipefail

BASE="https://router.flatkey.ai"
: "${FLATKEY_API_KEY:?Set FLATKEY_API_KEY before running this script}"

RESPONSE=$(curl -sS "$BASE/v1/videos" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      { "type": "text", "text": "An astronaut walking on the moon, cinematic lighting" }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }')

TASK_ID=$(echo "$RESPONSE" | jq -r '.id')
echo "task: $TASK_ID"

while true; do
  RESULT=$(curl -sS "$BASE/v1/videos/$TASK_ID" \
    -H "Authorization: Bearer $FLATKEY_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  echo "status: $STATUS"

  [ "$STATUS" = "completed" ] && break
  if [ "$STATUS" = "failed" ]; then
    echo "failed: $(echo "$RESULT" | jq -r '.error.message')" >&2
    exit 1
  fi
  sleep 5
done

VIDEO_URL=$(echo "$RESULT" | jq -r '.metadata.url')
curl -L "$VIDEO_URL" -o output.mp4
echo "saved -> output.mp4"

​エンドポイント

​リクエスト

​ヘッダー

​ボディパラメーター

​content アイテム

​動画編集

​ドラフトモード

​リクエスト例

​最初と最後のフレームの入力

​マルチモーダル参照

​レスポンス

​レスポンスフィールド

​タスクステータスのポーリング

​ステータスの値

​タスクコールバック

​動画のダウンロード

​エラー

​エンドツーエンドの例

エンドポイント

リクエスト

ヘッダー

ボディパラメーター

`content` アイテム

動画編集

ドラフトモード

リクエスト例

最初と最後のフレームの入力

マルチモーダル参照

レスポンス

レスポンスフィールド

タスクステータスのポーリング

ステータスの値

タスクコールバック

動画のダウンロード

エラー

エンドツーエンドの例