非同期APIでは、応答が遅いことと生成の失敗を同一視しないようにします。Higgsfield経由のSeedance 2.5を使った3回の観測から、送信前の予算判定、Idempotency-Key、request_idの保存、状態確認までを実装する際のチェック項目をまとめます。
リクエストの中身と音声の扱い
POST https://api.higgsfield.ai/bytedance/seedance-2.5/image-to-video
{
"prompt": "Slow forward aerial drift over the coffee shrubs, mist drifts
through the valleys, sunrise light slowly grows, realistic motion",
"image_url": "https://.../c4.png",
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"output_format": "mp4",
"generate_audio": false
}
送ったリクエストの本文（image_url は事前にアップロードした画像のURL）
generate_audio を false にしたので、できた動画には音声が入っていません。同じ画像から作ったKling 3.0 Proの動画には音声トラックが付いていたので、編集では音を消して使いました。音楽や効果音は別に作るつもりなら、最初から音声を生成しない指定にしておくと扱いやすくなります。
再試行しないための記録の残し方
動画生成は1回ごとに費用がかかるため、通信が途中で切れたときに自動で送り直すと、同じ動画に2回払うことがあります。今回は次のように記録を残し、結果が分からない生成は送り直さない作りにしました。
-
送る前に、モデル・本文・計算した金額を書いた記録を作る
-
送るときに一意のキー（Idempotency-Key）を付ける
-
返ってきた request_id と status_url をすぐに保存する
-
記録があって受付の控えがない生成は、送り直さずに状態を確かめる
Seedanceの費用は見積もりの式から計算する
Higgsfield APIには、生成する前に費用を返す見積もりの機能があります。Kling 3.0 Proでは金額（5秒で0.84ドル）がそのまま返ってきましたが、Seedance 2.5では金額ではなく料金の計算式の説明が返ってきました。そこで説明文の式を使い、送る前に金額を計算しています。
import math
SIZE = {'480p': (854, 480), '720p': (1280, 720)}
def usd(res, seconds=5):
w, h = SIZE[res]
tokens = math.ceil(h * w * seconds * 24 / 1024)
return tokens / 1000 * 0.0214
usd('720p') # 2.311
usd('480p') # 1.028
説明文の式を計算するコード。1,000トークンあたり0.0214ドル（480p・720p）
計算した金額を記録し、合計が上限の8ドルを超える生成はスクリプトが送信前に止める作りにしました。実際に返ってきた動画は720pが1280×720、480pが854×480で、計算に使った大きさと同じでした。
送信から完了まで待つ方法と実際の待ち時間
送信するとすぐに request_id と status_url が返り、状態は queued でした。動画ができるまでは status_url を約20秒ごとに確認し、状態が in_progress から completed に変わったら動画のURLから取得します。
status = call(receipt['status_url'])
if status['status'] == 'completed':
download(status['video']['url'])
状態の確認。completed になったら video.url から取得する
480p ハンドドリップ
約4分24秒
720p ハンドドリップ
約7分53秒
720p 高地の畑
約14分
失敗
3本とも1回目で完了
待ち時間は送信から取得できた確認までの時間で、確認の間隔の分（約20秒）だけ誤差があります。同じ720pの5秒でも約8分と約14分で差があり、混み具合によって変わると考えられます。待つ処理には上限を設け、時間内に終わらなくても同じ生成を送り直さないようにしています。
実装前のチェックリスト
-
モデル名・利用経路・設定・確認日を記録する
-
少数の試作で結果を確かめ、費用と再試行の上限を決める
-
生成物の権利、画面の文字、音声を公開前に人が確認する
本稿の数字は制作時の観測で、性能比較や待ち時間の保証ではありません。
比較用の出力と素材
詳しい条件と制作記録：Seedance APIで動画を作る｜生成・待機・費用の記録