how-tos

Seedance 2.5 APIガイド:cURLとPythonでSeedance 2.5 Flashを呼び出す

Poyo.ai Team
6 min read
Share:

夜明けに時計塔と競走する自転車の配達員を描いた、Seedance 2.5 Flash APIガイドのエディトリアルイラスト

Seedance 2.5 Flash APIは、Seedance 2.5 APIのより高速で低コストなティアで、PoYoでは1つのモデルID seedance-2.5-flash で利用できます。ByteDanceは2026年11月12日にリリースしました。Seedance 2.5 Flashのモデルページにはプレイグラウンドと最新の料金があります。このガイドでは、2026年11月16日に確認したSeedance 2.5 Flash APIドキュメントのスキーマに基づき、最初のcURLリクエストからPythonによる本番用ループまでを解説します。

Seedance 2.5 Flash APIの概要

項目値
送信エンドポイントPOST https://api.poyo.ai/api/generate/submit
ステータスエンドポイントGET https://api.poyo.ai/api/generate/status/{task_id}
認証ヘッダーAuthorization: Bearer $POYO_API_KEY
モデルIDseedance-2.5-flash(ページのスラッグ seedance-2-5-flash はモデルIDではない)
必須フィールドprompt、duration
長さ整数の秒数、4〜30
解像度480p または 720p、デフォルトは 720p
アスペクト比auto、21:9、16:9、4:3、1:1、3:4、9:16、デフォルトは auto
音声generate_audio、デフォルトは true
結果の受け取り非同期タスク:ステータスをポーリングするか callback_url を設定

cURLでSeedance 2.5 APIに最初のリクエストを送る

キーを POYO_API_KEY としてエクスポートし、ブラウザのコードではなくサーバー側で管理してください。これは5秒・480pのテキストから動画生成のリクエストで、92.5クレジットで済む低コストな最初のテストです。

curl --fail-with-body https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5-flash",
    "input": {
      "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot, gentle water sounds, no speech, no subtitles.",
      "duration": 5,
      "resolution": "480p",
      "aspect_ratio": "16:9"
    }
  }'

送信に成功すると code: 200 と、task_id、status(送信直後は常に not_started)、created_time を含む data オブジェクトが返ります。これは受付票であり、動画ではありません。task_id を保存してから、ステータスを照会します。

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

ステータスは not_started、running、finished、failed と遷移します。タスクが finished になると、動画のURLは file_type: "video" を持つ data.files[].file_url に入ります。failed の場合は data.error_message を確認してください。生成されたファイルにアクセスできるのは3日間なので、自分のストレージにコピーしてください。

Python:厳格な期限付きで送信とポーリングを行う

ステータスのドキュメントでは、2〜5秒ごとのポーリング、429 と 5xx でのバックオフ、そして常にタイムアウトを設定することが推奨されています。以下のループはこの3つをすべて行い、タイムアウト時にも再送信しません。2回目の送信は、課金対象の2つ目のタスクになるからです。

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]


def checked(response):
    try:
        body = response.json()
    except ValueError:
        response.raise_for_status()
        raise
    if body.get("code") != 200:
        err = body.get("error") or {}
        raise RuntimeError(
            f"PoYo {body.get('code')} {err.get('type')}: "
            f"{err.get('message') or body.get('detail')}"
        )
    return body["data"]


task = checked(session.post(BASE + "/api/generate/submit", json={
    "model": "seedance-2.5-flash",
    "input": {
        "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
        "duration": 5,
        "resolution": "480p",
        "aspect_ratio": "16:9",
    },
}, timeout=60))
task_id = task["task_id"]
print("Saved task:", task_id, flush=True)

deadline = time.monotonic() + 15 * 60
backoff = 5
while time.monotonic() < deadline:
    r = session.get(f"{BASE}/api/generate/status/{task_id}", timeout=60)
    if r.status_code == 429 or r.status_code >= 500:
        time.sleep(backoff)
        backoff = min(backoff * 2, 60)
        continue
    data = checked(r)
    if data["status"] == "failed":
        raise RuntimeError(data.get("error_message") or "Generation failed")
    if data["status"] == "finished":
        videos = [f["file_url"] for f in data.get("files", [])
                  if f.get("file_type") == "video"]
        print(videos[0], "credits:", data.get("credits_amount"))
        break
    backoff = 5
    time.sleep(5)
else:
    raise TimeoutError("Still running; poll the saved task ID later: " + task_id)

参考までに、2026年11月16日のPoYoのテストでは、4秒・480pのクリップはエンドツーエンドで約2分、30秒・720pのクリップは3分未満で完了しました。所要時間は負荷によって変わるため、15分の期限は見積もりではなく安全のための上限です。

ポーリングを省く:callback_urlを使う

model と同じ階層にトップレベルの callback_url を追加します。タスクが finished または failed になると、PoYoはタスクのデータオブジェクト(task_id、status、files、created_time、error_message)を code/data のラッパーなしでボディとするPOSTを送ります。動画のWebhookドキュメントによれば、次のとおりです。

  • URLは公開されたHTTPSで、2048文字以内、プライベートIPは不可。
  • 30秒以内に2xxで応答すること。配信に失敗した場合は、指数バックオフで最大5回再試行される。
  • X-Webhook-Signature を base64(HMAC-SHA256(task_id + "." + timestamp, key)) として検証する。timestamp は X-Webhook-Timestamp から、キーは GET /api/api-keys/webhook-secret から取得する。
  • ハンドラーは冪等にする。すべての再試行が失敗しても、ステータスエンドポイントで結果を取得できる。

3つの入力モードとJSONボディ

APIは送信されたメディアからモードを選択します。mode フィールドはありません。

モード選択される条件アスペクト比
参照から動画生成reference_image_urls、reference_video_urls、reference_audio_urls のいずれかが空でないサポートされている任意の値
画像から動画生成(先頭/末尾フレーム)image_urls が空でないauto または省略。出力は先頭フレームに従う
テキストから動画生成メディアなしサポートされている任意の値

image_urls と参照フィールドは別々のリクエストで送ります。以下のボディはドキュメントに掲載されている例です。

テキストから動画生成(720pで30秒、プロンプト内に時間指定のショットリスト):

{
  "model": "seedance-2.5-flash",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "One continuous 30-second story of the same young woman in a yellow raincoat delivering a handwritten letter across a small seaside town at dawn. 0-6s: wide aerial shot of the sleepy harbor town, fishing boats rocking, soft morning light; she rides an old bicycle down a cobblestone hill. 6-12s: tracking shot beside her as she weaves past a fish market, seagulls lifting off, a vendor waves at her. 12-18s: low-angle shot as she climbs a steep stone staircase carrying the bicycle, breathing hard, the letter tucked in her pocket. 18-24s: she knocks on a blue door at the top; an elderly man opens it and she hands him the letter. 24-30s: close-up of the man reading, his eyes filling with tears; he smiles and says softly, \"She remembered.\" Camera slowly pulls back to reveal the sunrise over the sea. Natural ambient sound: waves, gulls, bicycle bell, footsteps, gentle piano music. No subtitles, no on-screen text.",
    "duration": 30,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }
}

先頭/末尾フレーム(1つ目のURLで冒頭を、2つ目のURLで結末を固定):

{
  "model": "seedance-2.5-flash",
  "input": {
    "prompt": "Locked-off time-lapse of the red lakeside cabin: start from the summer evening in the first frame, let snow gradually cover the shore and the wooden dock as the sky darkens, and end exactly on the snowy night with the aurora in the last frame. Soft wind and crackling ice.",
    "image_urls": [
      "https://example.com/first-frame.jpg",
      "https://example.com/last-frame.jpg"
    ],
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "auto"
  }
}

参照から動画生成(ファイルはアップロード順に @Image1、@Video1、@Audio1 として参照):

{
  "model": "seedance-2.5-flash",
  "input": {
    "prompt": "@Image1 is the ginger cat. It wears the yellow knitted scarf from @Image2 and is inside the bookstore from @Image3. On a rainy night the cat walks along a bookshelf, jumps down beside a reading lamp, and looks at the camera. Match the slow, cozy rhythm of @Audio1. No subtitles.",
    "reference_image_urls": [
      "https://example.com/cat.png",
      "https://example.com/scarf.png",
      "https://example.com/bookstore.png"
    ],
    "reference_audio_urls": [
      "https://example.com/rhythm.mp3"
    ],
    "duration": 6,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }
}

送信前に確認しておきたいバリデーションルール

これらをクライアント側でチェックすれば往復を1回省け、汎用的な 400 よりもわかりやすいメッセージをユーザーに示せます。

フィールドルール
prompt必須、空でない文字列
duration必須の整数、4〜30
resolution480p または 720p のみ。1080p には seedance-2.5 が必要
aspect_ratio7つの値のいずれか。image_urls を使う場合は auto にするか省略
image_urls1〜2個のURL(先頭フレーム、次に末尾フレーム)。JPEG、PNG、WebP、各30 MBまで。参照フィールドとは併用不可
reference_image_urls最大10個。JPEG、PNG、WebP、各30 MBまで
reference_video_urls最大5個。MP4またはMOV、各2〜30秒・200 MBまで。合計の長さは30秒まで
reference_audio_urls最大5個。MP3またはWAV、各2〜30秒・15 MBまで。合計の長さは30秒まで。参照画像または参照動画が必要
すべてのメディアURL公開されたHTTPまたはHTTPSで、直接ダウンロードできること(ログインページや期限付きのプレビューは不可)

参照の合計の長さはタスクの送信時にチェックされます。スキーマでは input に additionalProperties: false も設定されているため、seed や negative_prompt など他社APIのフィールドは送らないでください。

対処しておきたいエラー

ボディの code フィールドは必ず確認してください。送信エンドポイントのバリデーションエラーの一部は、HTTP 200で "code": 400 として返ります。エラーコードのリファレンスには次のものが記載されています。

コードタイプ対処
400validation_error、file_format_error、content_moderation_errorリクエストまたはメディアを修正する。変更せずに再試行しない
401authentication_errorBearerヘッダーと、キーがまだ存在するかを確認する
402insufficient_credits_errorチャージしてから再送信する
429レート制限ポーリングや送信を再開する前にバックオフする(1秒、2秒、4秒...)
500、502、503サーバーまたは上流ステータスの呼び出しをバックオフ付きで再試行し、再送信の前にステータスを確認する
タスクが failederror_message が設定されるタスクIDを記録する。失敗したタスクは credits_amount: 0 と報告される

最初の請求額の計算方法

参照動画がない場合、費用は出力の秒数×秒単価です。480pで18.5クレジット($0.0925)、720pで41クレジット($0.205)で、1クレジット = $0.005です。生成される音声に追加料金はかかりません。

上記のリクエスト課金秒数クレジットUSD
cURLのテスト、5秒 480p592.5$0.4625
テキストから動画生成、30秒 720p301,230$6.15
先頭/末尾フレーム、5秒 720p5205$1.025
参照画像 + 音声、6秒 480p6111$0.555

reference_video_urls を1つでも追加すると、より低い動画入力ありの単価(480pで11.5クレジット、720pで25.5クレジット)が課金秒数に適用されます。課金秒数は、出力の長さに、各参照動画の長さを整数秒に切り捨てたものを加えた値です。Seedance 2.5 APIの料金解説では、こうしたケースを計算しています。完了したタスクの請求額は、ステータスのレスポンスに credits_amount として表示されます。

1080pにはSeedance 2.5に切り替える

リクエストのフィールドは同じなので、ジョブをFlashから標準のSeedance 2.5モデルに移すには、モデルIDを変えるだけです。

{
  "model": "seedance-2.5",
  "input": {
    "prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }
}

注意点が2つあります。seedance-2.5 のドキュメントでは resolution が必須とされているので必ず送ること、そして標準モデルでは最大30枚の画像、10本の動画、10個の音声を参照に使えることです。1080pでは1秒あたり114クレジット($0.57)です。振り分けの判断についてはSeedance 2.5 Flash vs Seedance 2.5を、Seedance 2.5と他社ベンダーの比較についてはKling 4.0 vs Seedance 2.5を参照してください。

よくある質問

Seedance 2.5 Flash APIのモデルIDは何ですか? ドット区切りの seedance-2.5-flash です。ハイフン区切りの seedance-2-5-flash はモデルページのスラッグにすぎません。

Seedance 2.5 Flash APIは1080pに対応していますか? いいえ。受け付けるのは 480p と 720p です。ネイティブの1080pが必要なら、同じボディを "model": "seedance-2.5" と "resolution": "1080p" で送ってください。

Seedance 2.5 APIで音声をオフにするには? 無音のクリップにするには "generate_audio": false を設定します。または音声をオンのままにして、「no background music」のようにプロンプトで個別のレイヤーを除外します。

1つのSeedance 2.5 Flashリクエストで先頭フレームと参照画像を併用できますか? いいえ。image_urls と reference_* フィールドは別々のリクエストで送る必要があります。

Seedance 2.5 Flash APIのタスクにはどのくらい時間がかかりますか? 2026年11月16日のPoYoのテストでは、エンドツーエンドで4秒・480pが約2分、30秒・720pが3分未満でした。リクエストを開いたまま待つのではなく、ポーリングかコールバックを使ってください。

Seedance 2.5 Flashのタスクが失敗した場合、課金されますか? いいえ。失敗したタスクは課金されず、ステータスには credits_amount: 0 と表示されます。

Share: