チュートリアル
seedance-2.5 画像から動画生成 API の呼び出し方法:利用可能な curl と Python の例
このページの内容
seedance-2.5 画像から動画生成エンドポイントが提供するもの
seedance-2.5 画像から動画生成は HiAPI 上の非同期モデルエンドポイントで、1枚または2枚の静止画像を短い動画クリップに変換します。画像(または動きの始点と終点として機能する1組の画像)を送信し、期待する変化を記述すると、プラットフォームはタスクを返し、生成が完了するとそのタスクは動画ファイルの URL に解決されます。
典型的な動画生成スタックにおいて、このエンドポイントは「静止画像を動かす」という層に位置します。すでにソース画像——製品画像、キャラクターのレンダリング、絵コンテのフレーム——があり、必要なのは新しい画像ではなく動きです。呼び出しは非同期であるため、あなたの仕事はタスクを送信し、タスク識別子を保持し、結果が準備できるまでポーリングを続けることです。この送信してからポーリングするパターンは HiAPI の長時間実行生成エンドポイントに共通するため、ここで書いたクライアントは他のモデルにも移植できます。
このエンドポイントはネイティブ音声オプションも提供しており、後から音楽を付ける無音素材ではなく、音声付きの動画クリップを処理フローで必要とする場合に重要です。フレーム単位で正確なカメラワークやループ可能な動きが必要な場合、明示的な最初のフレームと最後のフレームを使った画像から動画生成は、3D シーンを構築せずに最も制御しやすい選択肢となることが多いです。
前提条件と認証
初回の呼び出し前に、3つ用意してください。
1. HiAPI API キー
すべてのリクエストはあなたのキーで認証され、Authorization ヘッダーにベアラートークンとして送信されます。ソース管理にコミットしないでください——環境変数から読み取ることで、同じスクリプトがローカルでも CI でも実行できます。
export HIAPI_API_KEY="your_key_here"
2. API から取得可能なソース画像
画像入力は URL です。画像はサービスがアクセスできる場所にホストしてください——署名付き URL のオブジェクトストレージ、CDN、または任意の公開 HTTPS アドレスです。画像を公開したくない場合は、バケットを公開するのではなく、短時間有効な署名付き URL を生成してください。
最初のフレーム/最後のフレームのワークフローでは、1枚の画像(最初のフレームのみ)または2枚の画像(最初のフレームと最後のフレーム)が必要です。
3. HTTP クライアント
JSON を送信できるものであれば何でも構いません:迅速なスモークテスト用の curl、Python の requests または httpx、Node の fetch などです。特別な SDK は不要です。
このモデル固有のベース URL、パス、フィールド名は HiAPI コンソールのモデルページにあります。以下の例ではこれらの値をそのまま使用してください。キーと画像 URL が用意できたら、送信できます。
最初のフレーム入力と最後のフレーム入力
2つの画像入力は動画クリップの異なる端点を制御し、どちらを選ぶかで動きの制御度が変わります。
最初のフレームのみ。 1枚の画像を提供すると、モデルはそこから前方に向かって生成します。モデルに動きを自ら創造してほしい場合に適切な選択です:ゆっくり振り向くポートレート、回転する製品、雲が流れる風景など。クリップがどこで終わるかの確実性は放棄しますが、より大きな創作の余地が得られ、素材は1つで済みます。
最初のフレームと最後のフレーム。 2枚の画像を提供すると、モデルはそれらの間のパスを生成します。端点が重要な場合に適切な選択です:最終的な合成ロゴに組み合わされるロゴ、ポーズ A からポーズ B へ移動するキャラクター、画面の左から右へスライドする物体など。最後のフレームを提供すると動きが制約され、通常は意外な結果が減り、クリップを繰り返し再生する予定ならより良いループ性が得られます。
実用的なルール:クリップを「この画像に何か変化が起きる」と説明できるなら、最初のフレームのみを使用してください。「この画像があの画像になる」と説明できるなら、2枚を提供してください。2枚を提供する場合は、構図、アスペクト比、照明を2枚の画像で一致させてください——不一致な画像ペアは、モデルにグリッチのように見えるジャンプを処理させることになります。
プロンプトは画像を補完するものであり、衝突するものではありません。モデルがすでに見える静的な内容ではなく、動きを記述してください。
curl で最初のリクエストを送信する
以下のリクエストは画像から動画生成タスクを送信します。エンドポイントパス、モデル識別子、フィールド名は HiAPI コンソールの seedance-2.5 画像から動画生成モデルページに表示される値に置き換え、自分の画像 URL に差し替えてください。
curl -X POST "$HIAPI_BASE_URL/<image-to-video-path>" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5/image-to-video",
"prompt": "The camera slowly pushes in as the subject turns toward the light",
"first_frame_image": "https://your-cdn.example.com/frame-01.jpg",
"last_frame_image": "https://your-cdn.example.com/frame-02.jpg"
}'
リクエスト構造について、いくつか注意すべき点があります:
promptは動きを記述します。短く具体的に保ってください。形容詞の長いリストは指示を薄めることがよくあります。first_frame_imageは画像から動画生成に必須です。last_frame_imageはオプションです——最初のフレームのみで生成する場合はこのフィールドを完全に削除してください。- 音声オプションが必要な場合、それらは同じ JSON 本文内の追加フィールドです(後述します)。
レスポンスは識別子とステータスを含むタスクオブジェクトです。その識別子を保存してください。ポーリングのたびに必要になります。呼び出しが認証または検証エラーを返した場合は、再試行する前にまずヘッダーと画像 URL を確認してください。
Python での同じリクエスト
以下は Python での同等の送信コードで、タスク識別子を取得しやすいように再構成されています。
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<image-to-video-path>"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def submit_video(first_frame, last_frame=None, prompt="", audio=False):
payload = {
"model": "seedance-2.5/image-to-video",
"prompt": prompt,
"first_frame_image": first_frame,
}
if last_frame:
payload["last_frame_image"] = last_frame
if audio:
payload["audio"] = True
resp = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
resp.raise_for_status()
data = resp.json()
return data["task_id"], data
task_id, raw = submit_video(
first_frame="https://your-cdn.example.com/frame-01.jpg",
last_frame="https://your-cdn.example.com/frame-02.jpg",
prompt="The camera slowly pushes in as the subject turns toward the light",
)
print(task_id)
早めに身につける価値のある習慣が2つあります。第一に、送信呼び出しに明示的な timeout を設定してください——ハングしたリクエストはワーカーをブロックするのではなく、すぐに失敗すべきです。第二に、開発中は生のレスポンスを保持してください。タスク識別子を保存するフィールドはエンドポイントのバージョンによって task_id と異なる場合があるため、生の JSON を一度印刷しておくとデバッグの手間を1ラウンド省けます。
動画が準備できるまで非同期タスクをポーリングする
画像から動画生成には、単一の HTTP リクエストが開いたままにすべき時間を超える時間がかかるため、プラットフォームは送信してからポーリングするライフサイクルを採用しています。送信はタスク識別子を返します。その後、タスクエンドポイントを定期的に照会し、そのステータスが終了状態に達するまで続けます。
import time
import requests
def wait_for_video(task_id, interval=5, max_wait=600):
url = f"{BASE_URL}/<task-path>/{task_id}"
deadline = time.time() + max_wait
while time.time() < deadline:
resp = requests.get(url, headers=HEADERS, timeout=30)
resp.raise_for_status()
task = resp.json()
status = task.get("status")
if status == "succeeded":
return task["video_url"]
if status in ("failed", "cancelled"):
raise RuntimeError(f"Task {task_id} ended as {status}: {task.get('error')}")
time.sleep(interval)
raise TimeoutError(f"Task {task_id} not ready after {max_wait}s")
ポーリングは4つのルールに基づいて設計してください:
- 適度な間隔でポーリングする。 5秒は妥当なデフォルトです。エンドポイントを叩き続けても動画のレンダリングは速くなりません。
- 常に期限を設定する。 タスクは失敗したり、予想より長くキューに入ったりする場合があります。無制限のループは一時的な問題をスタックしたワーカーに変えてしまいます。
failedとcancelledを終了状態として扱う。 同じタスクを永遠に再試行するのではなく、エラーフィールドを公開してください。- 継続的なポーリングにはバックオフを使用する。 多数のタスクを同時にポーリングする場合は、バーストトラフィックを避けるために間隔を徐々に広げてください。
本番環境では、Web リクエストハンドラー内でポーリングするのではなく、バックグラウンドワーカーまたはキューからポーリングしてください。結果は動画 URL です。生成されたアセット URL は通常永続的ではないため、速やかにダウンロードして自分のストレージにコピーしてください。
ネイティブ音声フラグの扱い
seedance-2.5 はネイティブ音声付きのクリップを生成でき、この制御項目は画像入力やプロンプトと並ぶリクエストフィールドです——別のエンドポイントではありません。正確なフィールド名と許容値はモデルページに記載されています。上記の Python ヘルパー関数は audio ブール値を渡すことで例示しています。
有効にするかどうかは、クリップの消費方法によって決まります。
以下の場合は音声を要求する: 出力が直接視聴者に向けられる場合——ソーシャル投稿、プレビュー、デモ——そして二次編集なしでクリップを完成したものに感じさせたい場合。ネイティブ音声は、音があることで動きのタイミングが読み取りやすくなるため、レビュアーがリズムを判断するのにも役立ちます。
以下の場合は音声をスキップする: 処理フローが独自の音楽を重ねる場合、クリップを合成や編集ツールに渡す場合、または多くのバリエーションを生成して最終的に選ばれたバージョンだけに音楽を付ける予定の場合。無音生成は素材をニュートラルに保ち、後の同期問題を避けます。
範囲を絞るための実用的な注意点:音声はグローバル設定ではなく、リクエストごとの決定として扱ってください。上記のように audio フラグを受け取る単一のヘルパー関数により、同じコードパスで無音のバックグラウンドバッチ処理と洗練された最終レンダリングの両方に対応できます。
フラグが存在するのに結果が無音の場合は、モデルが無視したと仮定する前に、値が期待どおりにシリアライズされていることを確認してください——文字列 "true" とブール値 true はよくある不一致です。
よくある失敗ポイントと次のステップ
初回の統合問題のほとんどは4つのカテゴリに分類できます。
サービスが取得できない入力
ブラウザでは動作する URL がサーバー側で失敗する場合があります:プライベートバケット、期限切れのリンク、非ブラウザのユーザーエージェントをブロックするホストなどです。生成プロセス全体をカバーする有効期間を持つ署名付き URL を使用し、画像があなたのネットワーク外のマシンから読み込めることを確認してください。
不一致なフレーム
最初のフレームと最後のフレームがアスペクト比、クロップ、色温度で異なる場合、モデルはそのジャンプを調和させなければなりません。送信前に、画像ペアを同じサイズと近い色調に前処理してください。
誤ったフィールド名またはモデル識別子
ここの例はモデルページのリクエスト構造を使用しています。フィールド名とモデル文字列は、記憶や古い断片からではなく、コンソールからそのままコピーしてください。フィールド名のタイプミスは拒否されるのではなく、静かに無視されることがよくあります。
終了しないポーリング
ループが繰り返しタイムアウトする場合は、観察したすべてのステータス値を記録してください。予期しないステータス文字列を見ることで、通常は停滞の原因が説明できます——終了状態のチェックが API が返す内容と単に一致していないだけかもしれません。
単一のクリップがエンドツーエンドで動作したら、自然な次のステップは、同じ送信とポーリングのヘルパー関数で複数の画像をバッチ処理し、送信の周囲にバックオフ付きのリトライを追加し、結果を永続ストレージに書き込むことです。エンドポイントの詳細、リクエストフィールド、パラメータリファレンスは seedance-2.5 画像から動画生成モデルページで確認でき、それに基づいて上記のコードを自分の画像に適合させてください。