FLUX 3 Max API：hiapi でテキストから動画、画像から動画、キーフレームを利用する

概要

• hiapi 上の FLUX 3 Max は、同じ POST /v1/tasks エンドポイント上の 3 つの独立したモデル ID、すなわち flux-3-max/text-to-video、flux-3-max/image-to-video、flux-3-max/keyframes-to-video です。モードの切り替えは model と 1 つの入力フィールドを変更するだけです。
• いずれも 5〜20 秒、720p または 1080p のクリップを生成でき、出力秒数と解像度に基づいて課金されます。最新の価格は /en/pricing をご確認ください。
• キーフレームのフレーム番号の規則は、送信時にチェックされません。タイムラインに誤りがあっても API は HTTP 200 と taskId を返しますが、タスクは約 2 秒後に失敗します。事前にローカルで検証してください。

本ガイドは Max ティアを対象としています。ドラフトモードと動画の続き生成を備えた基本の flux-3 モデルについては FLUX.3 動画 API ガイド を、既存素材の編集については flux-3 動画編集 をご覧ください。

前提条件

hiapi コンソールでキーを作成し、エクスポートします：

export HIAPI_KEY=sk-your-key

すべてのモードでリクエストの流れは同じです：POST /v1/tasks が taskId を返し、その後 GET /v1/tasks/<taskId> をポーリングする（またはコールバックを使用する）と、status が success になるまで待ち、data.output[0].url をダウンロードします。

入力に応じてどのモデル ID を使うか

手持ちの入力	モデル ID	変更が必要な入力
テキストプロンプトのみ	flux-3-max/text-to-video	prompt
静止画 1 枚（任意で末尾フレームをもう 1 枚）	flux-3-max/image-to-video	image_url、任意で end_image_url
特定の時刻に必ず配置したい 1〜10 枚の画像	flux-3-max/keyframes-to-video	keyframes: [{image_url, frame_index}]

3 者共通の任意フィールド：duration（整数秒、5〜20、デフォルト 5）、resolution（720p または 1080p）、aspect_ratio（auto、21:9、2:1、16:9、4:3、1:1、3:4、9:16）、generate_audio（真偽値、デフォルト有効）、reasoning_level（low または high、デフォルト high）。モデルページ：テキストから動画、画像から動画、キーフレームから動画。

最小例：curl でテキストから動画

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/text-to-video",
    "input": {
      "prompt": "a slow aerial shot of ocean waves at sunrise, photorealistic",
      "duration": 5,
      "resolution": "720p",
      "generate_audio": false,
      "reasoning_level": "low"
    }
  }'

リクエストが有効な場合は {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"} が返ります。その後：

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-... -H "Authorization: Bearer $HIAPI_KEY"

generate_audio を無効にし 5 秒・low 推論で実行する設定は、プロンプトの効果を安価に試す方法です。モデルページによれば、音声は価格を変えません。

3 モードすべてをカバーする 1 つの Python ヘルパースクリプト

# pip install requests
import os, time, requests

KEY = os.environ["HIAPI_KEY"]
H = {"Authorization": f"Bearer {KEY}"}
BASE = "https://api.hiapi.ai/v1/tasks"

def submit(mode: str, **inp) -> str:
    """mode: text-to-video | image-to-video | keyframes-to-video"""
    body = {"model": f"flux-3-max/{mode}", "input": inp}
    res = requests.post(BASE, json=body, headers=H, timeout=30).json()
    if res.get("code") != 200:
        # sync 400s look like {"code":400,"error_code":"INVALID_REQUEST","message":"invalid input: ..."}
        raise RuntimeError(res)
    return res["data"]["taskId"]

def wait(task_id: str, timeout_s: int = 900, every: int = 10) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{BASE}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(d.get("error"))
        time.sleep(every)
    raise TimeoutError(task_id)

# 1) text-to-video
t2v = submit("text-to-video",
    prompt="A single white sneaker rotates slowly on a wet black plinth, studio softbox lighting, macro product shot",
    duration=5, resolution="720p", aspect_ratio="16:9", generate_audio=False)

# 2) image-to-video: first frame, optional last frame
i2v = submit("image-to-video",
    prompt="Morning mist drifts over the harbor; the boats rock gently and the camera slowly pushes forward.",
    image_url="https://example.com/harbor.jpg",
    # end_image_url="https://example.com/harbor-end.jpg",   # optional fixed ending
    duration=5, resolution="720p", generate_audio=False)

# 3) keyframes-to-video
FPS = 24
def keyframes_ok(duration: int, frames: list[dict]) -> None:
    idx = [f["frame_index"] for f in frames]
    assert 1 <= len(frames) <= 10, "1-10 keyframes"
    assert len(set(idx)) == len(idx), "frame_index must be unique"
    assert all(0 <= i <= duration * FPS for i in idx), f"frame_index must be 0..{duration * FPS}"

frames = [
    {"image_url": "https://example.com/harbor.jpg", "frame_index": 0},
    {"image_url": "https://example.com/latte.jpg",  "frame_index": 120},
]
keyframes_ok(5, frames)
kf = submit("keyframes-to-video",
    prompt="A continuous cinematic morph from the misty harbor into a close-up of an iced matcha latte.",
    keyframes=frames, duration=5, resolution="720p", generate_audio=False)

url = wait(kf)
open("clip.mp4", "wb").write(requests.get(url).content)

出力 URL は期限切れになるため、タスク成功後はリンクを保存するのではなく、すぐにダウンロードするかファイルをコピーしてください。

キーフレーム：タイムラインの仕組み

frame_index はパーセントではなく、0 から始まる 24 fps クロック上の位置です。許容される最大値は duration × 24 で、5 秒なら 120、10 秒なら 240、20 秒なら 480 です。インデックスは一意である必要があり、1〜10 個のキーフレームを渡せます。きれいな A から B への遷移を実現するには、最初のアンカーを 0 に、最後を duration × 24 に配置します。最後のアンカーを早めると結末を保持でき、遅らせると変化を圧縮できます。すべてのキーフレームでアスペクト比を統一してください。シームレスなループが必要な場合は、先頭と末尾の画像が同じ瞬間のように見えるようにします。

本番環境での注意点

• ポーリングとコールバック。 タスク API は callback.url と when: "final" を受け付けるため、ポーリングを省略できます。上記のように 10 秒ごとにポーリングする方法も、スクリプトやバッチタスクでは問題ありません。
• ポーリングループには必ずタイムアウトを設定し、ポーリング前に taskId を永続化して、プログラムのクラッシュで支払い済みのタスクを失わないようにしてください。
• すぐにダウンロード。 output[0].url は短期間のみ有効なものとして扱ってください。
• コスト管理。 課金は出力秒数と解像度に基づいて計算されるため、20 秒 1080p のクリップのコストは 5 秒 720p のテストの数倍になります。まず 5 秒・720p でプロトタイプを作り、プロンプトが有効になってから両方を引き上げてください。現在の料金は価格ページをご覧ください。

テストしたこと、していないこと

これらの確認は 2026 年 10 月 23 日に、読み取り専用のテストキーを使用して本番 API に対して行いました。本記事では完全なクリップをレンダリングしていないため、出力品質についての断言は行いません。サンプルプロンプトはモデルページに付属する例から引用しています。

同期バリデーション（HTTP 400、キュー未登録）。 範囲外の値は送信時に拒否され、error_code: INVALID_REQUEST と読みやすい message が返ります：

リクエスト	レスポンスの message
duration: 3	invalid input: duration: minimum: got 3, want 5
resolution: "4k"	value must be one of '720p', '1080p'
aspect_ratio: "5:4"	value must be one of 'auto', '21:9', '2:1', '16:9', '4:3', '1:1', '3:4', '9:16'
reasoning_level: "medium"	value must be one of 'low', 'high'
画像から動画で image_url ではなく image_urls を使用	image_url: missing required field "image_url"; ... additional properties 'image_urls' not allowed

最後の行はよくある間違いです。hiapi の他の画像入力モデルは複数形のフィールドを使用しますが、FLUX 3 Max の画像から動画は単一の image_url のみを受け付けます。未知のフィールドは無視されるのではなく拒否されます。

キーフレームのタイムラインエラーは非同期です。 私はタイムラインに問題のある 2 つの 5 秒キーフレームリクエストを送信しました。1 つは frame_index: 121（上限 120 を超過）を使用し、もう 1 つは 2 つのキーフレームがどちらも frame_index: 0 でした。両方とも受け付けられ、HTTP 200 と taskId が返りました。作成後約 1〜2 秒のポーリングで終端状態が返りました：

{"code":200,"data":{"status":"fail","model":"flux-3-max/keyframes-to-video",
 "error":{"code":"INVALID_REQUEST","message":"Invalid request parameters for this model. Please check the request and try again."},
 "taskId":"tk-hiapi-..."},"message":"success"}

ここから 2 つのことが分かります。第一に、送信が 200 を返してもタイムラインが有効であるとは限らないため、ポーリング時に status と error.code を確認する必要があります。第二に、失敗メッセージは非常に一般的で、どのフレームに問題があるかを示しません。これが、上記の keyframes_ok チェックを送信前に実行する価値がある理由です。モデルページによれば、失敗したタスクには課金されません。私はこれら 2 つのタスクの請求記録を確認していません。

よくある質問

最初のフレームと最後のフレームを使うには、どのモデル ID を使えばよいですか？ flux-3-max/image-to-video を使用し、image_url と end_image_url を渡します。最初と最後の間にアンカーを設定する必要がある場合にのみ、キーフレームを使用してください。

キーフレームを増やすと高くなりますか？ モデルページによれば、いいえ。課金は出力秒数と解像度に基づいて計算され、アンカーの数は価格に影響しません。

flux-3 との違いは何ですか？ flux-3-max/* は独立したモデル ID で、モードごと（テキスト、画像、キーフレーム）に分かれています。一方、基本の flux-3 は 1 つの ID で、入力に応じてモードを切り替え、ドラフトモードと続き生成もサポートします。FLUX.3 動画 API ガイドをご覧ください。私は両者の出力品質を比較していないため、機能と価格ページの料金に基づいて選択してください。

他の画像から動画モデルに切り替えられますか？ はい。他の画像から動画の選択肢については Ray 3.2 画像から動画 API の使い方をご覧ください。