ナビゲーションにスキップ

Seedance 2.0 Fast

テキスト、開始フレームと終了フレーム、または最大 9 枚の画像・3 本の動画・3 件の音声を参照として使い、Seedance 2.0 より低価格で、480p・720p の 4~15 秒の動画を生成します。

  • 非同期です。作成の呼び出しはタスク ID を返し、動画はタスクが成功した時点で得られます(通常は数分です)。
  • 入力方法は 4 通りです。テキストのみ、開始フレーム、開始フレームと終了フレーム、または参照画像・参照動画・参照音声の任意の組み合わせです(音声には、画像または動画を少なくとも 1 つ添える必要があります)。
  • 480p と 720p のみに対応し、同じ解像度では Seedance 2.0 より低価格です。
  • 音声はデフォルトで生成され(generate_audio)、料金は変わりません。
  • 料金は、動画のサイズと長さ、および参照動画の長さに応じて決まります。失敗したタスクには課金されません。
POST/v1/videos/tasks試してみる

このモデルをテスト画面で開きます。BeatAPI の API キーを入力するとタスクを作成できます。実際に呼び出され、ご自身の残高から課金されます。

モデル ID

4 つの Seedance モデルが、このエンドポイントを共有します。以下の値はゲートウェイの仕様から直接取得したものです。task_type、output_format、seed を受け付けるのは Seedance 2.5 のみです。

モデル IDduration(秒)resolution参照画像の最大数参照動画の最大数参照音声の最大数選ぶ場面
seedance-2.54–30480p, 720p, 1080p301010最長 30 秒のクリップ、大量の参照素材、動画の編集や延長、または MOV 出力が必要な場合。
seedance-24–15480p, 720p, 1080p, 4k9334K 出力が必要な場合、または 1080p を 2.5 より低価格で使いたい場合。
seedance-2-fast4–15480p, 720p933480p または 720p でより低価格にしたく、generate_audio も使いたい場合。
seedance-2-mini4–15480p, 720p933価格を最優先する場合。480p または 720p で、generate_audio フィールドはありません。

エンドポイントと認証

POST https://api.beatapi.io/v1/videos/tasks

Authorization string 必須

BeatAPI の API キーを Bearer <BEATAPI_API_KEY> の形式で送信します。キーはダッシュボードで作成できます。キーはサーバー側で保管し、ブラウザーやモバイルアプリに含めないでください。

ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値(255 文字以内)を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。

リクエストの流れ

1

タスクを作成する

下記のパラメーターをエンドポイントに POST します。201 が返れば、タスクが受け付けられ、料金が残高から仮確保されたことを意味します。処理はバックグラウンドで実行されます。data.id を保存してください。

2

完了を待つ

GET /v1/tasks/{task_id} を呼び出し、status が succeeded または failed になるまで、呼び出しの間隔を data.poll_after_seconds(画像は 5 秒、動画は 8 秒)だけ空けてください。あるいは task.succeeded と task.failed のWebhookを登録することもできます。処理タイムアウトで停止したタスクはイベントを送信しないため、フォールバックとしてポーリングも続けてください。

3

結果を保存する

succeeded の場合は、すべての data.output.media[].url をダウンロードし、必要なファイルを保存してください。結果 URL がいつまで利用できるかは保証されません。failed の場合は、data.error_code と data.error_message を確認してください。仮確保された金額は残高に戻されます。data.retryable は、同じリクエストをもう一度送れば成功する可能性があるかどうかを示します。

入力モード

モード必須の入力備考
テキストから動画model、promptメディアの配列は送らないでください。
開始フレームmodel、prompt、images(リンク 1 個)動画はその画像から始まります。
開始フレームと終了フレームmodel、prompt、images(リンク 2 個)images[0] が開始フレーム、images[1] が終了フレームです。
参照model、prompt、および reference_images・reference_videos・reference_audios のうち少なくとも 1 つ任意の組み合わせが可能ですが、音声には参照画像または参照動画を少なくとも 1 つ添える必要があります。images とは併用できません。

リクエストパラメーター

model string 必須

実行するモデルです。

値:seedance-2-fast

値が正しくない場合

  • 指定がない場合:"model" is required
  • 画像モデルをこのエンドポイントに送った場合:"model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint

prompt string 必須

動画の中で起きること(被写体、動き、カメラワーク、スタイル、音)です。参照を使う場合は、各入力が何のためのものかを書いてください。

長さ:1–5000 文字

  • 長さは文字数で数えます(CJK 文字も 1 文字として数えます)。
  • 入力は位置で指し示します。たとえば「1 本目の参照画像」「2 本目の参照動画」のように書きます。

値が正しくない場合

  • 指定がない場合:"prompt" is required
  • 空、または上限を超える長さの場合:"prompt" has an unsupported length

images string[] 任意

開始フレーム、または開始フレームと終了フレームです。

要素数:1–2
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。

  • リンクが 1 個の場合:動画はその画像から始まります。リンクが 2 個の場合:images[0] が開始フレーム、images[1] が終了フレームです。
  • より多くの画像を使う場合や、フレームではなく動画を導くための画像を使う場合は、代わりに reference_images を使ってください。

値が正しくない場合

  • リンクが 3 個以上の場合:"images" accepts at most 2 items
  • いずれかの reference_* フィールドと併用した場合:Cannot combine "images" with reference inputs in one task
  • https:// のリンクでない場合:"images[0]" must be a public HTTPS URL

reference_images string[] 任意

動画の内容、キャラクター、商品、スタイルを導くための画像です。

要素数:1–9
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。

  • 画像はリストの順に使われます。プロンプトでは位置で指し示してください。

値が正しくない場合

  • 最大数を超えた場合:"reference_images" accepts at most 9 items
  • images と併用した場合:Cannot combine "images" with reference inputs in one task

reference_videos string[] 任意

動き、カメラワーク、内容の参考にする動画です。

要素数:1–3
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。

  • 各リンクは、MP4 または MOV ファイルを返し、かつホストがバイトレンジリクエストに対応している必要があります。参照動画の秒数は課金対象のため、ゲートウェイはタスクを作成する前にすべてのクリップの長さを読み取ります。
  • 各クリップは 1.8~15 秒で、すべてのクリップの合計は 15 秒までです。

参照動画は、再生される秒数ごとに料金に加算されます(課金を参照)。必要な部分だけに切り詰めてください。

値が正しくない場合

  • 最大数を超えた場合:"reference_videos" accepts at most 3 items
  • クリップを読み取れない場合:A reference video could not be read: reference_videos[0]: its host does not allow byte-range requests. Send an MP4 or MOV file at a public HTTPS URL whose host allows byte-range requests.

reference_audios string[] 任意

従わせたい音楽、音声、サウンドです。音声だけを参照にすることはできません。参照画像または参照動画を少なくとも 1 つ添えてください。

要素数:1–3
各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。

  • WAV と MP3 のクリップは下の上限に照らして長さなどが測定されます。それ以外の形式は、測定されずにモデルへそのまま渡されます。

値が正しくない場合

  • 最大数を超えた場合:"reference_audios" accepts at most 3 items
  • 参照画像も参照動画もなく音声だけを送った場合:seedance-2-fast audio reference requires at least one reference image or video

duration integer 任意デフォルト: 5

動画の長さを秒単位の整数で指定します。

デフォルト:5
範囲:4–15

  • 省略すると 5 が送られます。

値が正しくない場合

  • 範囲外、または整数でない場合:"duration" is outside its supported range

aspect_ratio string 任意デフォルト: adaptive

動画の形を「幅:高さ」で指定します。adaptive を指定すると、モデルが入力から形を選びます。

指定できる値:adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16
デフォルト:adaptive

  • adaptive を指定した場合、仮確保額は選択した解像度の最大のフレームを想定して計算されるため、アスペクト比を固定した場合よりもわずかに高くなることがあります。

値が正しくない場合

  • 一覧にない値の場合:"aspect_ratio" must be one of: [adaptive 21:9 16:9 4:3 1:1 3:4 9:16]

resolution string 任意デフォルト: 720p

出力の解像度で、480p または 720p です。720p のほうが 1 秒あたりの料金が高くなります。

指定できる値:480p, 720p
デフォルト:720p

  • 小文字のみ使えます。1080p と 4K はこのモデルでは使えません(seedance-2 を使ってください)。

値が正しくない場合

  • 一覧にない値の場合(たとえば 1080p や 720P):"resolution" must be one of: [480p 720p]

generate_audio boolean 任意デフォルト: true

動画に生成されたサウンドトラックを付けるかどうかです。どちらでも料金は同じです。

デフォルト:true

値が正しくない場合

  • true または false でない場合:"generate_audio" must be a boolean

ゲートウェイはタスク作成前に、次の組み合わせも確認します。

  • images と参照メディアのフィールドは同時に使用できません。

入力メディアの上限

ゲートウェイはタスク作成前にすべての入力を読み取り、次の上限を超えるものは、その入力を示す 400 bad_request で拒否します。課金はされません。

メディアタスク作成前に確認される上限
画像幅・高さとも 300~6000 px;アスペクト比(幅 ÷ 高さ)0.4~2.5;1 件あたり 30 MB 以下
動画1 本あたり 1.8~15 秒;合計 15 秒以内;1 フレームあたり 407,696 ピクセル以上(幅 × 高さ);24~60 FPS
音声1 本あたり 2~15 秒;合計 15 秒以内
  • 参照動画は MP4 または MOV で、ホストがバイトレンジリクエストに応答する公開 HTTPS リンクである必要があります。長さを読み取れないクリップは、その秒数が課金対象のため、常に拒否されます。
  • 画像のサイズは、ホストが報告する場合に確認されます。JPEG、PNG、WebP を使ってください。モデルが使えないファイルは、送信後にタスクが bad_request で失敗し、返金されます。
  • 上限違反は、長さ、辺、アスペクト比、ピクセル数、フレームレート、サイズの順に報告されます。メッセージには、リスト名と位置で入力が示されます。位置はフィールドのエラーと同じく 0 から数えます。たとえば reference_videos[0] is 1.5 seconds long; this model takes reference video of 1.8 to 15 seconds. のようになります。
  • 長さは 0.1 秒の許容誤差で測定されます。サイズは、ホストが報告する場合にのみ確認されます。
  • 画像と音声のリンクは、ホストが 4xx エラーを返した場合や空のファイルを返した場合にのみ、作成時に拒否されます。たとえば images[1] could not be downloaded: the URL returned HTTP 404. のようになります。それ以外の問題は、送信後に表面化します。
  • 23.976 FPS のクリップは 24 未満として扱われ、拒否されます。24 FPS 以上で書き出し直してください。
  • ローカルファイルは POST /v1/files でアップロードし、返された data.url を指定してください。

組み合わせのルール

これらはタスク作成時に、次の順で確認されます。いずれかに違反するリクエストは 400 bad_request で拒否され、課金されません。

リクエスト拒否メッセージ
images といずれかの reference_* フィールドの併用Cannot combine "images" with reference inputs in one task
参照画像も参照動画もない reference_audiosseedance-2-fast audio reference requires at least one reference image or video

このモデルが受け付けないフィールド

次のフィールドを送ると、無視されるのではなく、課金が発生する前に拒否されます。

  • 他の動画モデルのフィールド(seed、task_type、output_format(Seedance 2.5 のみ)、watermark、quality、sound、multi_shots、character_orientation など) → field "seed" is not supported by model seedance-2-fast(実際に送ったフィールド名が入ります)。
  • どの BeatAPI 動画モデルも使っていない名前 → unknown field: <name>。

価格の見積もり

タスクの動画トークン数は N = W × H × (24 × D + 1 + 24 × R) / 1024 です。W × H は、選択した解像度とアスペクト比でのフレームのピクセル数(16:9 の 720p なら 1280 × 720、16:9 の 480p なら 864 × 496)、D は出力の長さ(秒)、R は参照動画の合計の長さ(秒、ない場合は 0)です。料金は N に動画トークン 100 万あたりの単価を掛けたもので、480p と 720p で同じく、参照動画なしで約 5.575、参照動画ありで約5.575、参照動画ありで約 3.315 です。

たとえば、16:9・720p・5 秒で参照動画なしの場合は、1280 × 720 × 121 / 1024 = 108,900 トークンで、約 $0.607 です。参照動画の長さはゲートウェイが自分で測定するため、送信する必要はありません。参照クリップの長さはゲートウェイ自身が測定するため、これを含むボディは未知のフィールドとして拒否されます。これは見積もりです。タスクの usage に、仮確保額と実際の課金額が表示されます。

リクエスト例

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "seedance-2-fast",
"prompt": "A fast handheld tracking shot through a rain-lit night market, neon reflections on wet stone, ambient crowd sound",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}'

テキストから動画

音声付きの、5 秒・720p の横長クリップです。

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "seedance-2-fast",
"prompt": "A fast handheld tracking shot through a rain-lit night market, neon reflections on wet stone, ambient crowd sound",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
}'

開始フレーム

動画はその画像から始まります。

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "seedance-2-fast",
"prompt": "Animate the singer with a quick natural camera push-in",
"images": [
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"duration": 5,
"resolution": "720p"
}'

開始フレームと終了フレーム

動画は 1 枚目の画像から 2 枚目の画像へ移っていきます。

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "seedance-2-fast",
"prompt": "The camera pushes in from the bottle on the table to the singer on a neon stage in one continuous move",
"images": [
"https://cdn.beatapi.io/samples/smart-bottle.png",
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"duration": 6,
"resolution": "720p"
}'

画像と音声の参照

キャラクター画像と音楽クリップに従ったパフォーマンスです。

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "seedance-2-fast",
"prompt": "The singer from the first reference image performs on stage in time with the reference music, warm spotlights, slow orbiting camera",
"reference_images": [
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"reference_audios": [
"https://cdn.beatapi.io/samples/neon-singer-preview.mp3"
],
"duration": 8,
"resolution": "720p"
}'

画像・動画・音声の参照

動画のリンクを、15 秒以下の自分の MP4 または MOV に置き換えてください。参照動画は 1 秒ごとに課金されます(「課金」を参照)。

curl --request POST \
--url https://api.beatapi.io/v1/videos/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "seedance-2-fast",
"prompt": "A product film: the bottle from the first reference image on a turntable, camera movement like the first reference video, cut to the beat of the reference music",
"reference_images": [
"https://cdn.beatapi.io/samples/smart-bottle.png"
],
"reference_videos": [
"https://your-cdn.example.com/clips/source.mp4"
],
"reference_audios": [
"https://cdn.beatapi.io/samples/neon-singer-preview.mp3"
],
"duration": 8,
"resolution": "720p"
}'

レスポンス

タスクの作成(201)

タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "video",
"capability_id": "seedance-2-fast",
"capability_version": 1,
"media_type": "video",
"model": "seedance-2-fast",
"status": "queued",
"stage": "queued",
"created_at": 1791993600,
"updated_at": 1791993600,
"completed_at": null,
"poll_after_seconds": 8,
"output": null,
"usage": {
"credits_reserved": 0.496763,
"credits_settled": 0,
"credits_refunded": 0,
"credits_charged": 0.496763,
"billable_duration_seconds": 5
},
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": null,
"error_message": null
}
}
フィールド型説明
data.idstringタスク ID です。task_ の後に英数字 32 文字が続きます。ポーリングや Webhook イベントとの照合に使います。
data.objectstring常に task です。
data.task_kindstringimage または video です。
data.capability_idstring送信したモデル ID です。
data.capability_versionintegerモデルの仕様バージョンです。現在は 1 です。
data.media_typestringimage または video です。
data.modelstring送信したモデル ID です(capability_id と同じ)。
data.statusstringqueued、processing、succeeded、failed のいずれかです。最終状態は後ろの 2 つだけです。
data.stagestringstatus と同じ値です。古いクライアント向けに残されています。
data.created_atintegerタスクの作成日時(Unix 秒)です。
data.updated_atinteger最終更新日時(Unix 秒)です。
data.completed_atinteger | nullタスクの完了日時(Unix 秒)です。実行中は null です。
data.poll_after_secondsinteger実行中のみ。次のポーリングまでに待つ秒数です(画像は 5、動画は 8)。
data.typical_secondsobject実行中のみ、直近のタスクが十分にある場合に含まれます。直近 window の samples 件のタスクについて、完了までの時間(秒)の p50 と p90 を示します。
data.outputobject | null結果です。status が succeeded になるまでは null です。下の出力フィールドを参照してください。
data.usage.credits_reservednumberタスク作成時に残高から仮確保された金額(USD)です。
data.usage.credits_chargednumberこのタスクの料金(USD)です。失敗したタスクでは 0 です。
data.usage.credits_settlednumber最終的に差し引かれた金額(USD)です。タスクが成功した時点で設定され、それ以外では 0 です。
data.usage.credits_refundednumber残高に戻された金額(USD)です。失敗したタスクでは、返金が記録された時点で仮確保した金額と一致します。
data.usage.billable_duration_secondsinteger動画のみ。料金の算定に使われた秒数です。モデルが長さを報告しない場合は含まれません。
data.request_idstringリクエスト ID です。サポートに問い合わせる際に添えてください。
data.error_codestring | null失敗コードです。タスクが失敗した場合以外は null です。
data.error_messagestring | null何が問題で、何を変更すればよいかを示します。タスクが失敗した場合以外は null です。

完了したタスク

GET /v1/tasks/{task_id} は HTTP 200 と status: "succeeded" を返し、結果は data.output に入ります。

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "video",
"capability_id": "seedance-2-fast",
"capability_version": 1,
"media_type": "video",
"model": "seedance-2-fast",
"status": "succeeded",
"stage": "succeeded",
"created_at": 1791993600,
"updated_at": 1791993690,
"completed_at": 1791993690,
"output": {
"media": [
{
"type": "video",
"url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
"mime_type": "video/mp4"
}
],
"r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
},
"usage": {
"credits_reserved": 0.496763,
"credits_settled": 0.496763,
"credits_refunded": 0,
"credits_charged": 0.496763,
"billable_duration_seconds": 5
},
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": null,
"error_message": null
}
}

出力フィールド

フィールド型説明
output.mediaobject[]生成されたファイルです。このモデルでは動画 1 本です。
output.media[].typestring常に video です。
output.media[].urlstring保存された動画への HTTPS リンクです。ダウンロードして保管してください。保持期間は保証されません。
output.media[].mime_typestring常に video/mp4 です。
output.r2_urlstring動画の URL と同じ値です。古いクライアント向けです。代わりに media を読んでください。

失敗したタスク

失敗したタスクも、GET /v1/tasks/{task_id} では HTTP 200 になります。失敗はボディに示されます。仮確保された金額は全額戻されるため、課金されません。

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "video",
"capability_id": "seedance-2-fast",
"capability_version": 1,
"media_type": "video",
"model": "seedance-2-fast",
"status": "failed",
"stage": "failed",
"created_at": 1791993600,
"updated_at": 1791993690,
"completed_at": 1791993690,
"output": null,
"usage": {
"credits_reserved": 0.496763,
"credits_settled": 0,
"credits_refunded": 0.496763,
"credits_charged": 0,
"billable_duration_seconds": 5
},
"retryable": true,
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": "processing_failed",
"error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
}
}
フィールド型説明
data.error_codestringbad_request と content_policy_violation(リクエストを修正してください)、または processing_unavailable、processing_timeout、processing_failed、result_transfer_failed(時間をおいて再試行してください)のいずれかです。エラーを参照してください。
data.error_messagestring問題と対処方法を示す文です。
data.retryableboolean失敗したタスクにのみ含まれます。同じリクエストをもう一度送れば成功する可能性がある場合は true です。
data.usageobject返金が記録された時点(通常はタスクが失敗した瞬間)で、credits_charged と credits_settled は 0 になり、credits_refunded は credits_reserved と一致します。

完全なコード例

タスクを作成し、サーバーが示すポーリング間隔で完了を待ち、結果の URL を出力します。環境変数に BEATAPI_API_KEY を設定し、requests をインストールしてください。

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
# One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
for attempt in range(3):
response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
if response.status_code in (429, 503) and attempt < 2:
time.sleep(int(response.headers.get("Retry-After", 10)))
continue
break
try:
payload = response.json()
except ValueError: # an edge error page is not JSON
response.raise_for_status()
raise
if not response.ok:
error = payload["error"]
raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
deadline = time.monotonic() + timeout_seconds
while time.monotonic() < deadline:
response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
if response.status_code == 429 or response.status_code >= 500:
time.sleep(int(response.headers.get("Retry-After", 10)))
continue
response.raise_for_status()
task = response.json()["data"]
if task["status"] in ("succeeded", "failed"):
return task
time.sleep(task.get("poll_after_seconds", 5))
raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
"model": "seedance-2-fast",
"prompt": "A fast handheld tracking shot through a rain-lit night market, neon reflections on wet stone, ambient crowd sound",
"duration": 5,
"aspect_ratio": "16:9",
"resolution": "720p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
print(item["url"])

課金

  • 料金は、動画のサイズと長さに応じて決まります。秒数が長いほど、解像度が高いほど、フレームが大きいほど、料金は上がります。音声は料金に影響しません。参照画像と参照音声には、追加料金はかかりません。
  • 参照動画がない場合、16:9 のクリップは 1 秒あたり約 0.051(480p)、0.051(480p)、0.099(720p)です。ほかのアスペクト比では数パーセント異なります。
  • reference_videos を使うと、リクエスト全体がより低い「動画入力あり」の料金になり、参照動画の 1 秒ごとに出力 1 秒と同じ扱いで加算されます。16:9 の場合、出力と参照を合わせた 1 秒あたり約 0.030(480p)、0.030(480p)、0.059(720p)です。
  • 下の表は 8 秒のクリップの料金です。「動画入力あり」の行には、8 秒の参照動画が含まれています。
  • 料金はタスク作成時に仮確保されます。adaptive を使う場合、仮確保額はその解像度の最大のフレームを想定して計算されます。支払うのは仮確保額です。ただし、納品された動画の実際の金額がそれを上回る場合は、実際の金額になります。
  • 失敗したタスクは、送信後にモデレーションで拒否されたものも含め、全額が返金されます。

現在の定価です。料金ページと同じ金額です。割引を個別に契約しているアカウントでは、より低い金額になります。実際に課金された金額は、タスクの data.usage で確認できます。

オプション定価(USD)
8 秒 · 480p · 動画入力なし$0.409385
8 秒 · 480p · 動画入力あり$0.485575
8 秒 · 720p · 動画入力なし$0.792358
8 秒 · 720p · 動画入力あり$0.939822

よくあるエラー

エラーまたは症状原因対処
400 resolution "720p" is not available for this model right now; available: …このモデルを提供しているどの回線も、現時点ではその値を受け付けていません。aspect_ratio でも同様のことが起こり得ます。一覧にある値のいずれかを使うか、しばらくしてから再試行してください。
400 field "seed" is not supported by model seedance-2-fast他の動画モデルのフィールドを送っています。このモデルは受け付けません(seed、task_type、output_format、watermark、quality、sound、multi_shots、character_orientation)。そのフィールドを削除してください。seed、task_type、output_format を受け付けるのは Seedance 2.5 のみです。
400 "resolution" must be one of: [480p 720p]1080p、4k、720P、またはその他の値を送っています。480p または 720p を送ってください。1080p や 4K には seedance-2 を使います。
400 seedance-2-fast audio reference requires at least one reference image or videoreference_audios だけを送っています。参照画像または参照動画を追加してください。
400 Cannot combine "images" with reference inputs in one task同じリクエストでフレームと reference_* を併用しています。フレームか参照のどちらかを使ってください。複数の画像を使う場合は、すべて reference_images に入れます。
400 "duration" is outside its supported range4~15 の整数ではない、または文字列として送っています。5 のような整数を送ってください。
400 A reference video could not be read: reference_videos[0]: …MP4 または MOV ではない、ホストがバイトレンジに対応していない、404 になる、またはファイルが空です。レンジリクエストに対応した公開 HTTPS ストレージにクリップを置くか、POST /v1/files でアップロードしてください。
400 reference_videos[0] is 1.5 seconds long; this model takes reference video of 1.8 to 15 seconds.参照クリップが上限より短いか、長すぎます。クリップを切り詰めるか、差し替えてください。
400 The reference videos run 20 seconds in total; this model takes at most 15.参照クリップの合計が長すぎます。クリップを切り詰めるか、減らしてください。
タスクが content_policy_violation で failedプロンプト、入力、または結果がモデレーションで拒否されました(実在の人物、公人、著作権で保護されたキャラクターなど)。入力を変更してください。そのまま再試行しても再び失敗します。課金はされません。
402 insufficient_credits残高が仮確保額に足りません。長い参照動画と adaptive は仮確保額を押し上げます。残高をチャージするか、参照を短くするか、アスペクト比を固定してください。

HTTP エラー早見表

タスクが作られる前のエラーは、2xx 以外のレスポンスで返されます。課金はされません。error.code または error.retryable で処理を分岐してください。message には問題の内容が示されます。全一覧と再試行のルールはエラーにあります。

{
"error": {
"code": "bad_request",
"message": "\"prompt\" is required",
"retryable": false,
"request_id": "req_5f0c2a9e4b7d4e31"
}
}
HTTP ステータスerror.code対処方法
400bad_request, content_policy_violationリクエストを修正してください。メッセージにフィールド名が示されます。そのまま再試行しないでください。
401missing_api_key, invalid_api_key(古いクライアントでは unauthorized が返ることがあります)有効なキーを Authorization: Bearer <key> で送信してください。
402insufficient_credits残高をチャージするか、キーのクォータを引き上げてから、再度送信してください。
403forbiddenこのキーまたはアカウントでは、このモデルを利用できない可能性があります(たとえば、無料クレジットは一部のモデルにのみ使えます)。そのまま再試行しないでください。
404not_foundGET /v1/tasks/{task_id} の場合:このキーのアカウントに該当するタスクが存在しません。ID を確認してください。
409idempotency_conflict新しい Idempotency-Key を使うか、同じキーの最初のリクエストが完了するまで待ってください。
429rate_limit_exceededRetry-After の秒数(error.retry_after_seconds にも含まれます)だけ待ってから再試行してください。
500internal_errorバックオフを入れて再試行してください。解消しない場合は、request_id を添えてサポートにお問い合わせください。
503processing_unavailable, processing_timeout, processing_failed, result_transfer_failed課金はされていません。指数バックオフで再試行してください。

認証

AuthorizationBearer

API キーを Authorization: Bearer <BEATAPI_API_KEY> として送信してください。

ヘッダー

Idempotency-Keystringオプション<=255 characters

ボディは JSON で送信し、Content-Type: application/json を指定します。Idempotency-Key は任意です。論理的に 1 件のリクエストごとに一意の値(255 文字以内)を送り、まったく同じボディを再試行するときだけ再利用してください。24 時間以内に同じキーと同じボディで再試行すると、最初のレスポンスが Idempotent-Replayed: true 付きで再度返されます。同じキーで異なるボディを送ると 409 idempotency_conflict が返ります。2xx 以外のレスポンスは保存されないため、400 や 402 の後の再試行は改めて実行されます。

リクエスト

This endpoint expects an object.
modelenum必須

実行するモデルです。

値:seedance-2-fast

値が正しくない場合

  • 指定がない場合:"model" is required
  • 画像モデルをこのエンドポイントに送った場合:"model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint
許可された値:
promptstring必須1-5000 characters

動画の中で起きること(被写体、動き、カメラワーク、スタイル、音)です。参照を使う場合は、各入力が何のためのものかを書いてください。

長さ:1–5000 文字

  • 長さは文字数で数えます(CJK 文字も 1 文字として数えます)。
  • 入力は位置で指し示します。たとえば「1 本目の参照画像」「2 本目の参照動画」のように書きます。

値が正しくない場合

  • 指定がない場合:"prompt" is required
  • 空、または上限を超える長さの場合:"prompt" has an unsupported length
aspect_ratioenumオプションデフォルト値 adaptive

動画の形を「幅:高さ」で指定します。adaptive を指定すると、モデルが入力から形を選びます。

指定できる値:adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16

デフォルト:adaptive

  • adaptive を指定した場合、仮確保額は選択した解像度の最大のフレームを想定して計算されるため、アスペクト比を固定した場合よりもわずかに高くなることがあります。

値が正しくない場合

  • 一覧にない値の場合:"aspect_ratio" must be one of: [adaptive 21:9 16:9 4:3 1:1 3:4 9:16]
durationintegerオプション4-15デフォルト値 5

動画の長さを秒単位の整数で指定します。

デフォルト:5

範囲:4–15

  • 省略すると 5 が送られます。

値が正しくない場合

  • 範囲外、または整数でない場合:"duration" is outside its supported range
generate_audiobooleanオプションデフォルト値 true

動画に生成されたサウンドトラックを付けるかどうかです。どちらでも料金は同じです。

デフォルト:true

値が正しくない場合

  • true または false でない場合:"generate_audio" must be a boolean
imageslist of stringsオプション

開始フレーム、または開始フレームと終了フレームです。

要素数:1–2

各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。

  • リンクが 1 個の場合:動画はその画像から始まります。リンクが 2 個の場合:images[0] が開始フレーム、images[1] が終了フレームです。
  • より多くの画像を使う場合や、フレームではなく動画を導くための画像を使う場合は、代わりに reference_images を使ってください。

値が正しくない場合

  • リンクが 3 個以上の場合:"images" accepts at most 2 items
  • いずれかの reference_* フィールドと併用した場合:Cannot combine "images" with reference inputs in one task
  • https:// のリンクでない場合:"images[0]" must be a public HTTPS URL
reference_audioslist of stringsオプション

従わせたい音楽、音声、サウンドです。音声だけを参照にすることはできません。参照画像または参照動画を少なくとも 1 つ添えてください。

要素数:1–3

各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。

  • WAV と MP3 のクリップは下の上限に照らして長さなどが測定されます。それ以外の形式は、測定されずにモデルへそのまま渡されます。

値が正しくない場合

  • 最大数を超えた場合:"reference_audios" accepts at most 3 items
  • 参照画像も参照動画もなく音声だけを送った場合:seedance-2-fast audio reference requires at least one reference image or video
reference_imageslist of stringsオプション

動画の内容、キャラクター、商品、スタイルを導くための画像です。

要素数:1–9

各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。

  • 画像はリストの順に使われます。プロンプトでは位置で指し示してください。

値が正しくない場合

  • 最大数を超えた場合:"reference_images" accepts at most 9 items
  • images と併用した場合:Cannot combine "images" with reference inputs in one task
reference_videoslist of stringsオプション

動き、カメラワーク、内容の参考にする動画です。

要素数:1–3

各要素は公開されている https:// の URL です。ローカルファイルは先に アップロード(POST /v1/files)し、返された data.url を渡してください。

  • 各リンクは、MP4 または MOV ファイルを返し、かつホストがバイトレンジリクエストに対応している必要があります。参照動画の秒数は課金対象のため、ゲートウェイはタスクを作成する前にすべてのクリップの長さを読み取ります。
  • 各クリップは 1.8~15 秒で、すべてのクリップの合計は 15 秒までです。

備考:参照動画は、再生される秒数ごとに料金に加算されます(課金を参照)。必要な部分だけに切り詰めてください。

値が正しくない場合

  • 最大数を超えた場合:"reference_videos" accepts at most 3 items
  • クリップを読み取れない場合:A reference video could not be read: reference_videos[0]: its host does not allow byte-range requests. Send an MP4 or MOV file at a public HTTPS URL whose host allows byte-range requests.
resolutionenumオプションデフォルト値 720p

出力の解像度で、480p または 720p です。720p のほうが 1 秒あたりの料金が高くなります。

指定できる値:480p, 720p

デフォルト:720p

  • 小文字のみ使えます。1080p と 4K はこのモデルでは使えません(seedance-2 を使ってください)。

値が正しくない場合

  • 一覧にない値の場合(たとえば 1080p や 720P):"resolution" must be one of: [480p 720p]
許可された値:

レスポンス

タスクオブジェクトです。タスクが成功するまで output は null です。「実行中」と記載されたフィールドは、タスクの完了後に表示されなくなります。

エラー

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error