hiapi で hailuo-2.3-fast/image-to-video を使ってショート動画を一括生成する

ショート動画の成否はイテレーションの速さにかかっています。TikTok や Reels 向けのパイプラインを運用しているなら、映画品質の 4K 出力は必要ありません。必要なのは、商品の静止画を 1 分以内に使えるクリップへ変換してくれるモデルであり、しかも最良のバージョンを選ぶ前に何十ものバリエーションを試せる程度に安価であることです。まさにそれが hailuo-2.3-fast/image-to-video の立ち位置です。hailuo-2.3 の Fast ティアに当たる兄弟モデルで、価格設定もチューニングも、高スループットで使い捨て前提の複数回試行ワークフローに特化しています。

本ガイドでは、これをバッチ・ショート動画エンジンとして使う方法を解説します。ソース静止画の選び方、非同期タスク API での駆動方法、怠ると 400 エラーを食らうスキーマの細部の検証方法、そして TikTok/Reels 規模で運用する際のコスト感の考え方まで扱います。

モデルでできること

hailuo-2.3-fast/image-to-video は静止画とプロンプトを受け取り、短い動画クリップへアニメーション化します。hailuo-2.3-fast/image-to-video モデルページに掲載されており、hiapi 上の他のすべてのモデルと同様に、統一された/v1/tasks非同期エンドポイント経由で呼び出します。タスクを POST し、完了までポーリング（またはコールバックを登録）し、有効期限の短い出力 URL から動画を取得します。

本記事執筆時点で本番 API に対して検証済みの内容：

• 入力：画像 1 枚（image_url）+ 望む動きを記述したテキストプロンプト
• 出力：MP4、固定長 6 秒または 10 秒（任意の長さは不可）
• 価格：秒単位ではなく動画 1 本あたりの定額——6 秒クリップ $0.27、10 秒クリップ $0.46
• 所要時間：テストクリップはエンドツーエンド（送信 → 成功）で約 80 秒

動画 1 本あたりの定額という点がバッチ処理の鍵となる詳細です。6 秒の試行は、プロンプトが一発で狙った動きに当たっても、すでに 4 回目を試していても、コストは同じです。Fast ティアの価格なら、同じキービジュアルに対して 5〜6 個のバリエーションを走らせて最も滑らかな動きを選んでも、多くのハイエンド動画モデルの 1 回の試行より安く済みます。バッチの予算を組む前に、価格ページで最新の数字を確認してください——価格は変動します。

完全なパラメータリファレンス、より長い尺のオプション、あるいは非 Fast の hailuo-2.3 ティアとの並列比較が必要な場合は、hailuo-2.3-fast/image-to-video API 統合チュートリアルを参照してください。本ガイドは生の API リファレンスではなく、バッチ/ワークフローの観点に焦点を当てています。

ワークフロー：静止画 → ショートクリップ

ショート動画の定番はシンプルです。すでに手元にある静止画（商品撮影、生成したヒーローショット、ブランド素材）から始め、ゼロから動画を生成するのではなく、モデルに動きを加えさせます——ゆっくりしたプッシュイン、わずかな回転、漂う雰囲気など。これにより視覚的アイデンティティ（同じ商品、同じライティング、同じ構図）を固定しつつ、静止投稿ではないコンテンツを生み出せます。

実際に実行した事例を紹介します。ライティングされた台座の上に置かれた縦向き（9:16）のスニーカーの静止画を、ゆっくりしたプッシュインと穏やかな回転を記述したモーションプロンプトで駆動しました。

ソース静止画と完全なリクエスト：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hailuo-2.3-fast/image-to-video",
    "input": {
      "prompt": "Slow smooth push-in on a chunky retro basketball sneaker in wolf-gray suede with volt yellow laces, floating above a wet concrete pedestal, subtle rotation revealing the side panel, mist drifting through teal-to-amber rim light, dust particles catching the light, stable cinematic camera movement, premium commercial product-video finish",
      "image_url": "https://static.hiapi.ai/gallery/2026/07/c2e71481d2eb81a7.jpg",
      "duration": "6",
      "prompt_optimizer": true
    }
  }'

レスポンス：

{"code":200,"data":{"taskId":"tk-hiapi-01KZ5FJV0TB8EYKDCV58FQ1F2X"},"message":"success"}

解決するまでポーリング：

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KZ5FJV0TB8EYKDCV58FQ1F2X \
  -H "Authorization: Bearer $HIAPI_API_KEY"

{
  "status": "success",
  "output": [{"type": "video", "url": "https://temp.hiapi.ai/.../result.mp4", "expireAt": 1786421652}]
}

この output[0].url は一時的なものです——すぐにダウンロードし、自分のストレージへ転送・保存してください。ホットリンクしたり、安定した URL だと期待してデータベースのフィールドに保存したりしないでください。

入力スキーマ（本番 API に対して検証済み）

このモデルのスキーマは、プラットフォーム上の他の動画モデルから期待されるものよりずっと狭くなっています——アスペクト比の制御、解像度ティア、seed はありません。

フィールド	型	制約	必須
prompt	string	動き/シーンを記述	はい
image_url	string	単数——公開 URL 1 つ、配列ではない	はい
duration	string	列挙 "6" または "10"——文字列として、数値ではない	はい
prompt_optimizer	boolean	プラットフォームによるプロンプトの書き換え/拡張を許可	いいえ

他のモデルの前提を持ち込むと、400 エラーを招く 2 つの落とし穴があります：

1. image_url は単数で、image_urls ではありません。 hiapi 上の他のいくつかの i2v モデルは参照画像の配列を受け取りますが、このモデルは 1 枚のみです。配列を送ると、親切な型変換ではなくフィールド欠落エラーになります。
2. duration は文字列 "6" または "10" でなければならず、数値 6 ではありません。 数値 6 を送ると duration: got number, want string が返ります。さらに、この 2 値の列挙以外の値は受け付けられません——このティアには任意長の制御はありません。

aspect_ratio、resolution、seed、watermark を送ると——これらは兄弟モデルでは一般的なフィールドですが——additional properties ... not allowed を伴って即座に拒否されます。モデルは入力画像のアスペクト比を継承するため、Reels/TikTok 向けに 9:16 の出力が必要なら、送信前にソース静止画を 9:16 にクロップするか 9:16 で生成してください（上記のスニーカーの静止画はまさにそうしています）。

Python によるエンドツーエンド

import requests
import time

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "your-api-key"

def make_short_clip(prompt: str, image_url: str, out_path: str, duration: str = "6"):
    resp = requests.post(
        API_BASE,
        headers={"Authorization": f"Bearer {API_KEY}"},
        json={
            "model": "hailuo-2.3-fast/image-to-video",
            "input": {
                "prompt": prompt,
                "image_url": image_url,
                "duration": duration,  # must be a string: "6" or "10"
                "prompt_optimizer": True,
            },
        },
        timeout=60,
    )
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    while True:
        task = requests.get(f"{API_BASE}/{task_id}",
                             headers={"Authorization": f"Bearer {API_KEY}"},
                             timeout=30).json()["data"]
        if task["status"] == "success":
            break
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(8)

    video_url = task["output"][0]["url"]  # temporary link — download immediately
    video_bytes = requests.get(video_url, timeout=120).content
    with open(out_path, "wb") as f:
        f.write(video_bytes)
    return out_path

本当のバッチ実行——たとえば同じソース静止画に対して 6 つのプロンプトバリエーションを試して最も滑らかな動きを選ぶ——では、この関数をプロンプトのリストに対するループで包み、各 task_id を順番にブロックするのではなく個別に確認してください。1 クリップあたり約 80 秒として計算すると、複数を並列に走らせることこそが Fast ティアを本当に速く感じさせる秘訣です。

よくある質問

出力のアスペクト比を制御できますか？ いいえ——このモデルには aspect_ratio フィールドがなく、送ると 400 が返ります。出力は入力画像のアスペクト比に従うため、送信前に必要な比率でソース静止画を用意してください（Reels/TikTok なら 9:16、フィード投稿なら 1:1）。

なぜ私のリクエストは "got number, want string" で失敗するのですか？ duration を JSON の数値として送っています。文字列 "6" または "10" でなければなりません——有効な値はこの 2 つだけです。

これは hailuo-2.3/image-to-video（非 Fast）と同じモデルですか？ いいえ——Fast ティアは hiapi 上の独立した別価格のモデルで、独自のスキーマを持ち、標準ティアではなく速度とコスト向けにチューニングされています。バッチではないリファレンスのウォークスルーが必要な場合は、完全な統合チュートリアルを参照してください。

実写写真ではなく生成画像を入力できますか？ はい——ソース静止画は、公開アクセス可能な URL であれば、hiapi 上（または他の場所）の任意の画像モデルから生成したもので構いません。他のフォーマット向けにすでに出力済みの静止画（商品キービジュアル、ポスター）を使うのが、別途クリエイティブの工程を設けずに最短でショート動画を得る方法であることが多いです。

価格は解像度によって変わりますか？ このモデルには解像度パラメータがないため、入力画像の解像度に関わらず価格は尺ごとの定額です——本記事執筆時点で 6 秒 $0.27、10 秒 $0.46。価格ページで確認してください。

要点

• hailuo-2.3-fast/image-to-video は静止画 1 枚を 6 秒または 10 秒の MP4 に変換し、秒単位ではなく動画 1 本あたりの定額（$0.27 / $0.46）で課金——ソース画像ごとに複数のプロンプトバリエーションを走らせられるほど安価です。
• スキーマは意図的に狭く：prompt、image_url（単数）、duration（文字列列挙 "6"/"10"）、および任意の prompt_optimizer——アスペクト比、解像度、seed の制御はありません。
• 出力は入力画像のアスペクト比を継承するため、送信前にソース静止画を 9:16（またはプラットフォームに必要な任意の比率）で用意してください。
• 統合時によくある 2 つのミスは、image_url を配列で送ることと、duration を文字列ではなく数値で送ることです。
• バッチ・ショート動画ワークフローでは、動画 1 本あたりの定額と約 80 秒の所要時間により、素材ごとに 1 回だけ送信するのではなく、複数の試行を生成して最良の動きを選ぶことが現実的になります。

自分の商品画像で試してみる準備はできましたか？hailuo-2.3-fast/image-to-video モデルページで直接リクエストをテストするか、Fast ティアと他の画像から動画へのオプションをまず比較したい場合は完全なモデルカタログをご覧ください。