チュートリアル
HiAPI API で hailuo-2.3/image-to-video を呼び出す方法:curl と Python
このページの内容
hailuo-2.3/image-to-video にできること、使うべきタイミング
hailuo-2.3/image-to-video は、HiAPI の統一 API で提供される画像から動画を生成するモデルです。静止画像を最初のフレームとして渡し、画面がどのように動くべきかを記述したプロンプトを加えると、モデルはその画像から始まり、それを土台にアニメーションを進める短い動画を生成します。
キーワードは最初のフレームです。テキストから動画を生成する場合、モデルはプロンプトに基づいて画面全体をゼロから構想します。一方、画像から動画を生成する場合は、構図、被写体、光、スタイルを提供した画像に固定します。そのため、保持したい特定のビジュアル素材(製品画像、キャラクターの参考画像、絵コンテのコマ、コンセプトのレンダリング画像)がすでにあり、それを再解釈するのではなく動きを重ねたい場合に適した選択肢です。
このエンドポイントが適している場面:
- 既存の素材との一貫性が必要な場合。製品写真は、わずかに異なる製品として再生成されるのではなく、動き出すべきです。
- 静止フレームから絵コンテやアニマティックを構築しており、動きの効果をすばやくプレビューしたい場合。
- 制御可能な構図が必要な場合。カメラと被写体の位置は画像から決まり、プロンプトは動きだけを記述すれば済みます。
参考画像がなく、モデルにカメラワークを設計させたい場合や、ビジュアルの細部をフレームで固定するよりもテキストで表現する方が適している場合は、テキストから動画を生成する方を使うのが適しています。
前提条件と API キーの取得
最初のリクエストを行う前に、HiAPI アカウント、API キー、そして公開アクセス可能な最初のフレーム画像の URL という 3 つが必要です。
アカウントと API キー
HiAPI にログインし、コンソールで API キーを作成します。キーは機密情報として扱い、ソースファイルに貼り付けるのではなく環境変数に保存してください。このガイドのサンプルはすべて HIAPI_API_KEY から読み取ります。
export HIAPI_API_KEY="your-api-key-here"
アクセス可能な画像 URL
最初のフレームとして渡す画像はサーバー側から取得できる必要があります。署名付きクラウドストレージの URL、CDN リンク、任意の公開 HTTPS URL のいずれでも構いませんが、ローカルファイルのパスは使えません。素材が認証を必要とする場所にある場合は、リクエスト用に有効期限付きの署名付き URL を生成してください。
自動化を進める前に、最新の HiAPI API リファレンスで現在のエンドポイントパス、パラメータ名、許容値を確認してください。モデルのインターフェースは進化するため、古いチュートリアルで見たパラメータ名をハードコードすることは、よくある、かつ避けられる誤りの原因です。現在の価格やクォータのルールはウェブサイトの価格パネルに記載されています。推測せず、そこで確認してください。
リクエスト構造:画像入力とパラメータ
概念的には、画像から動画へのリクエストはモデル識別子、画像、生成パラメータの 3 つの部分から成ります。
モデル識別子
すべての呼び出しは hailuo-2.3/image-to-video を指します。コード内の 1 か所にまとめておけば、将来モデルを切り替える際に 1 行変更するだけで済みます。
最初のフレーム画像
これは動画の開始時点となる静止画像の URL です。そのアスペクト比と解像度が出力の基本的な形状を決めるため、後からトリミングするのではなく、すでに必要な構図になっている画像を選んでください。きれいで、照明が良く、被写体がはっきりした画像は、雑然としたコラージュ画像よりもはるかに予測可能な動きを生み出します。
プロンプト
動きを記述するテキストフィールドです。次のセクションで説明します。
長さと解像度
画像から動画へのタスクでは、通常、クリップの長さと出力解像度のオプションが提供されます。これらのパラメータはモデルのバージョンによって変わる可能性が最も高いため、記憶に頼ってハードコードしないでください。最新の API リファレンスを開き、受け入れられるフィールド名と許容値を読み、それらの値をコードのあちこちにリテラルとして散らばせるのではなく設定オブジェクトに入れてください。値が拒否された場合、通常は API のレスポンスがどのフィールドに問題があるかを示します。
リクエストボディは JSON で、レスポンスは完成した動画ではなくタスク識別子を返します。これについては以下のポーリングのセクションで説明します。
説得力のある動きを生み出すプロンプトの書き方
画像はすでにシーンに何があるかを記述しています。プロンプトの役割はそれがどのように動くかを記述することです。被写体を言い換えるプロンプトはモデルの能力を無駄にしますが、動き、カメラの挙動、物理法則を明確に述べるプロンプトは、はるかに優れた動画クリップを生み出します。
内容ではなく動きを記述する
悪い例:「赤いコートを着た女性が橋の上に立っている。」
良い例:「女性がゆっくりとカメラの方を向き、コートが風に揺れる。カメラは穏やかに前進する。」
被写体の動きとカメラの動きを分ける
両方について明確にしてください。「ゆっくりと前方へのプッシュイン」「手持ち風のドリフト」「固定カメラ」「右へのオービット」は、画面自体がどう変化するかをモデルに伝えます。一方、「髪がなびく」「湯気が立ち上る」「ページがめくれる」は、画面の内部で起きることを記述します。両者を組み合わせることで、漂流するのではなく一貫したショットが得られます。
物理法則に従う
合理的な速度で合理的な動きを要求してください:「布がそっと起伏する」「水が下流へ流れる」「煙が上へ巻き上がる」。シーンと矛盾する指示(座っている被写体に歩かせる、固定カメラの製品ショットに速いパンを要求するなど)は、通常アーティファクトにつながります。
簡潔かつ具体的に保つ
具体的で物理的な言葉による 2〜3 文は、形容詞の段落全体に勝ります。まず主要な動きを述べ、次にカメラを述べ、最後に光の変化などの二次的な細部を述べてください。
タスクを送信して結果をポーリングする
動画生成には時間がかかるため、API は非同期です。ライフサイクルは 3 つのステップに分かれます:
1. タスクを作成する
画像 URL、プロンプト、パラメータをエンドポイントに POST します。成功したレスポンスはタスク識別子と初期状態を返します。通常は queued や processing のようなものです。このレスポンスにはまだ動画は含まれていません。
2. タスクをポーリングする
そのタスク識別子に対して定期的に GET リクエストを送信します。各レスポンスは状態を報告し、完了時には結果のペイロードも含みます。タイトなループでポーリングするのではなく、通常は数秒間隔で適度な間隔を空けてポーリングし、試行回数を制限して、スタックしたタスクがプロセスを永久にハングさせないようにしてください。
3. 動画を取得する
状態が成功を報告したら、レスポンスには動画の場所(通常は URL)が含まれ、多くの場合、長さなどのメタデータも含まれます。自分の保存ルールに従ってダウンロードまたは保存してください。
本番環境向けの設計ポイント
- タスク ID を永続化する。 ワーカープロセスがポーリングの途中でクラッシュした場合、再送信して重複タスクに課金されるのではなく、復旧できるようにしたいはずです。
- 終端状態の失敗を処理する。 タスクは失敗する可能性があります。失敗は「ポーリングを続ける」のではなく、独立した分岐として処理してください。
- 送信とポーリングを分離する。 Web バックエンドでは、リクエストハンドラから送信し、バックグラウンドワーカーからポーリングすることで、HTTP タイムアウトが実行中の生成タスクを終了させることがなくなります。
実行可能な curl のサンプル
以下のサンプルはタスクを送信します。画像 URL とプロンプトを自分のものに置き換えてください。キーは先ほど設定した環境変数から取得します。
curl -sS -X POST \
"https://api.hiapi.ai/v1/hailuo-2.3/image-to-video" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://your-cdn.example.com/first-frame.jpg",
"prompt": "画面の被写体がわずかにカメラの方を向いて微笑む。カメラはゆっくりと前進し、柔らかな光が顔の上を流れる。"
}'
レスポンスにはタスク識別子が含まれます。GET リクエストでポーリングします:
curl -sS \
"https://api.hiapi.ai/v1/hailuo-2.3/image-to-video/TASK_ID" \
-H "Authorization: Bearer $HIAPI_API_KEY"
状態が終端の成功になるまで繰り返し、ペイロードから動画 URL を読み取ります。ここに示す正確なエンドポイントパスとフィールド名はパターンを説明するためのものにすぎません。モデルのインターフェースは実際に変化するため、本番コードに何かを貼り付ける前に最新の API リファレンスで確認してください。
実行可能な Python のサンプル
このスクリプトはタスクを送信し、完了するまでポーリングします。タイムアウトと基本的なエラー処理も含まれています。
import os
import time
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1/hailuo-2.3/image-to-video"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def create_task(image_url: str, prompt: str) -> str:
resp = requests.post(
BASE,
headers={**HEADERS, "Content-Type": "application/json"},
json={"image_url": image_url, "prompt": prompt},
timeout=60,
)
resp.raise_for_status()
data = resp.json()
task_id = data.get("task_id") or data.get("id")
if not task_id:
raise RuntimeError(f"No task id in response: {data}")
return task_id
def poll_task(task_id: str, timeout_s: int = 600, interval_s: int = 5) -> dict:
deadline = time.time() + timeout_s
while time.time() < deadline:
resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
resp.raise_for_status()
data = resp.json()
status = str(data.get("status", "")).lower()
if status in {"succeeded", "success", "completed"}:
return data
if status in {"failed", "error", "cancelled"}:
raise RuntimeError(f"Task {task_id} failed: {data}")
time.sleep(interval_s)
raise TimeoutError(f"Task {task_id} did not finish in {timeout_s}s")
if __name__ == "__main__":
task = create_task(
image_url="https://your-cdn.example.com/first-frame.jpg",
prompt="湯気がカップから立ち上る。カメラはゆっくりと右へドリフトする。",
)
result = poll_task(task)
print(result)
API のバージョンによって状態文字列が異なる可能性があるため、コードは単一のリテラルではなく、一般的な成功値と失敗値の小さな集合をチェックします。正確な語彙は API リファレンスで確認し、それに応じて集合を調整してください。複数のメディアパイプラインを構築する場合は、このヘルパー関数を独立させておくと再利用が容易になります。
よくある失敗パターンとデバッグ方法
このエンドポイントに関する問題のほとんどは、以下のいくつかのカテゴリに分類できます。
画像が拒否される、または取得できない
サービスがあなたの画像をダウンロードできる必要があります。取得エラーや検証エラーが発生した場合は、URL が公開 HTTPS かどうか、有効期限が切れていないか(署名付き URL は期限切れになります)、形式とサイズがドキュメントの制限内かどうかを確認してください。簡単な確認方法は、ブラウザのプライベートウィンドウでその URL を開くことです。ログインを求められる場合、サーバー側も同様に読み取れません。
パラメータが無効
拒否された長さ、解像度、または不明なフィールドは、通常、そのフィールドを指し示す検証エラーを返します。ペイロードはチュートリアルではなく最新の API リファレンスと比較し、完全なエラーボディを記録してください。エラーメッセージは HTTP ステータスコードだけよりも具体的です。
認証エラー
401 または 403 は、ほとんどの場合、キーが欠落している、形式が正しくない、またはアクセス権限がないことを意味します。Authorization ヘッダーが存在すること、および環境変数が実際にリクエストを実行しているシェルまたはプロセスでエクスポートされていることを確認してください。
ポーリングのタイムアウト
タイムアウト後もタスクが processing のままの場合、まず正しいタスク ID をポーリングしているか確認し、その後タイムアウトを延長してください。本番環境では、「まだ実行中」と「スタックしている」を区別する必要があります。再送信するとタスクを無駄にするため、状態を永続化してワーカープロセスにポーリングを再開させるようにしてください。
タスク送信後に失敗する
失敗したタスクは、通常、プロンプトと画像の組み合わせ(矛盾する動きの指示、または要求された動きと衝突する最初のフレーム)を示しています。プロンプトを簡素化し、よりクリーンな最初のフレームを試してから再実行してください。
出力がおかしい
動きが弱い、または奇妙な場合、修正方法はほぼ常にプロンプトにあります。主要な動きを明確に述べ、カメラの挙動と被写体の挙動を分け、物理的な動きを合理的に保ってください。リクエスト ID とタスク ID をログに記録し、不適切な動画クリップをそれを生成した正確な入力と関連付けられるようにしてください。公開前に、API リファレンスと価格パネルでパラメータ名と現在の価格を確認してください。