HiAPI API で flux-3-max/text-to-video を呼び出す方法：curl と Python ガイド

flux-3-max/text-to-video の機能と適用シーン

flux-3-max/text-to-video は HiAPI 上のテキストから動画へのエンドポイントです。シーンを描写するプロンプトを送信すると、モデルが生成した動画クリップを返します。既存の素材ではなくテキストの構想がある場合——たとえば製品予告、ソーシャルメディア向けの短尺動画、絵コンテのプレビュー、バッチ生成された空ショット——に、生成プロセスをセルフホストではなくマネージドタスクとして実行したいときに適したツールです。

動画がより大きなフローの一部にすぎないワークフローに適しています。スクリプト生成器がプロンプトを出力し、flux-3-max/text-to-video がそれを動画クリップに変換し、アプリケーションが結果を保存または配信する、という流れです。呼び出しが非同期であるため、レンダリング時間の間リクエストを開いたままにできないバックエンドサービスにも適しています。

既存の動画をフレーム単位で正確に編集する必要がある場合や、プロンプトが実際には単なる静止画像である場合には使用しないでください。後者の場合、テキストから画像へのエンドポイントの方が安価で高速です。出力が提供された素材に反応する必要がある場合は、画像から動画へのバリエーションを使用する必要があります。flux-3-max/text-to-video はプロンプトから動画クリップの生成への入口と捉え、同期レスポンスではなくタスクの投入を中心に統合を設計してください。

リクエスト構造：エンドポイント、認証、ペイロード

flux-3-max/text-to-video への各リクエストは3つの部分で構成されています：エンドポイントパス、認証ヘッダー、そしてモデルとその入力を指定する JSON リクエストボディです。

認証

HiAPI はベアラートークンを使用します。API キーを Authorization ヘッダーに入れてください：

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

キーはサーバー側に保持してください。クライアントコードに埋め込んだり、バージョン管理にコミットしたりしないでください。開発時は環境変数から、本番環境ではシークレットマネージャーからロードしてください。

モデル識別子

リクエストボディでは、model フィールドでエンドポイントを選択します。正確な識別子 flux-3-max/text-to-video を使用してください。ここでのスペルミスはリクエストが拒否される最も一般的な原因です。

ペイロード構造

最小のリクエストボディはモデル名とプロンプトを含みます：

{
  "model": "flux-3-max/text-to-video",
  "prompt": "日の出の時刻、霧に包まれた松林の上空をゆっくりと移動する空撮、映画のようなライティング"
}

オプションフィールド——再生時間とネイティブ音声スイッチ——については次のセクションで説明します。生成は非同期であるため、この POST リクエストの即時レスポンスは識別子を持つタスクオブジェクトであり、完成した動画を直接取得するのではなく、その識別子をポーリングする必要があります。コードはまずその識別子を読み取り、その他の情報は二次的に扱うように設計してください。

再生時間とネイティブ音声の制御

2つのリクエストレベルの制御項目が得られる結果を決定します：動画クリップの再生時間と、モデルが動画の生成と同時に音声を生成するかどうかです。

再生時間

ペイロードの duration フィールドでクリップの長さを設定します。物語を満たす最短の再生時間を選択してください——短い動画はレンダリングが速く、レビューも容易で、いつでも追加リクエストできます。送信前に flux-3-max/text-to-video のドキュメントに記載された範囲に従って値を検証してください。範囲外の再生時間は送信時に拒否されるため、ローカルでその問題を捕捉すれば1回の往復を節約できます。

ネイティブ音声

ネイティブ音声スイッチは、モデルが動画クリップとともに音声トラックを生成するかどうかを決定します。動画が音声付きで視聴される場合はオンにし、動画がミュートされる場合、字幕が付けられる場合、またはポストプロダクションで別途音楽が付けられる場合はオフにしてください。破棄する音声を生成することはタスク時間を増やすだけで何の利益もありません。

意識的な選択

デフォルト値に判断を委ねないでください。迅速な絵コンテレビューには、短く無音のクリップで通常は十分です。最終的なソーシャルメディア素材には、ネイティブ音声付きの長めのクリップが目標になるかもしれません。その選択は呼び出し箇所にハードコードするのではなく、アプリケーション設定にエンコードしてください。そうすればリクエストコードを変更せずに機能ごとに変更できます。実際に上書きしたいフィールドのみを送信し、残りのフィールドはエンドポイントがデフォルト値を適用するに任せてください。

利用可能な curl リクエスト

認証情報とペイロードを確認する最速の方法は、1回の curl 呼び出しでタスクを送信することです。

curl -X POST "$HIAPI_BASE_URL/v1/videos/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-max/text-to-video",
    "prompt": "雨に濡れた通りを漂う紙のボート、暖かい街灯、浅い被写界深度",
    "duration": 5,
    "native_audio": false
  }'

まずシェルで HIAPI_BASE_URL と HIAPI_API_KEY を設定してください。ここの再生時間と音声の値はあくまで例です——モデルのドキュメントに記載された範囲内の値を使用してください。

即時レスポンスの読み取り

レスポンスは動画ではなくタスクオブジェクトです。これには job_id（または同等の識別子）と、queued や processing といったステータスが含まれます。この識別子を保存してください。それが以降のすべての呼び出しのハンドルになります。レスポンスがエラーオブジェクトに見える場合は、再試行する前にステータスコードとメッセージを確認してください——形式が正しくないペイロードは毎回同じように失敗します。

送信の成功はタスクが受け入れられたことだけを意味し、それ以上のものではありません。最初のレスポンスで動画 URL を探そうとしないでください。タスクが完了するまでそこには現れません。

非同期タスクのライフサイクルの処理

動画生成には数秒から数分かかるため、HiAPI はそれをタスクとしてモデル化しています。クライアントは1回送信し、タスクが終端状態に達するまでステータスを確認します。

ステータス

タスクは queued から processing を経て終端状態——completed または failed——に進みます。終端状態のみが最終状態であり、その間のどの状態も待機を続けることを意味します。

過剰なポーリングを避ける

保存したタスク識別子を使用してステータスエンドポイントをポーリングします。ポーリングを健全に保つ2つのルール：

• ポーリングの間に待機する。 短い間隔から始めて徐々にバックオフするか、典型的なキュー待ち時間より明らかに長い固定間隔を使用してください。ステータスエンドポイントへの過剰なリクエストには何の利益もありません。
• 上限を設定する。 総待機時間と総試行回数を制限してください。その時点でタスクが完了していない場合は、無限ループではなくアプリケーションにエスカレーションしてください。

Web ハンドラーでは、リクエストスレッドをポーリングループでブロックさせないでください。送信し、タスク識別子を保存し、すぐに戻り、バックグラウンドワーカーまたはクライアントにライフサイクルの完了をポーリングさせてください。バッチ処理のシナリオでは、sleep を伴う単純なループで十分です。

結果の読み取り

タスクが completed と報告されたとき、レスポンスには出力参照——アプリケーションがダウンロードまたはストリーミングできる動画 URL またはアセットハンドル——が含まれます。失敗時は error フィールドを読み取ってください。通常は原因（無効なパラメータ、コンテンツ拒否、内部エラー）を示します。タスク識別子と失敗メッセージを一緒にログに記録して、サポートリクエストや再試行の根拠にしてください。出力フィールドの欠落を成功と見なしてはいけません——ステータスを明示的に確認してください。

Python での同じリクエスト

curl のフローは Python に直接マッピングできます。最小のクライアントには送信、ポーリングループ、そして不正なリクエストと遅いタスクを区別するのに十分なエラー処理が必要です。

import os, time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit(prompt, duration=5, native_audio=False):
    body = {
        "model": "flux-3-max/text-to-video",
        "prompt": prompt,
        "duration": duration,
        "native_audio": native_audio,
    }
    resp = requests.post(f"{BASE}/v1/videos/generations",
                         headers=HEADERS, json=body, timeout=30)
    resp.raise_for_status()
    return resp.json()["job_id"]

def wait(job_id, interval=5, max_attempts=60):
    for attempt in range(max_attempts):
        time.sleep(interval)
        r = requests.get(f"{BASE}/v1/videos/generations/{job_id}",
                         headers=HEADERS, timeout=30)
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "completed":
            return data
        if status == "failed":
            raise RuntimeError(data.get("error", "job failed"))
    raise TimeoutError(f"job {job_id} did not finish in time")

実装の説明

raise_for_status() は転送および HTTP エラー（認証、ペイロード形式の誤り）を、成功レスポンスの内部に現れるタスクレベルの失敗と区別します。failed チェックはステータスが completed であると仮定するのではなく、error フィールドを明示的に読み取ります。試行回数の上限は無制限の待機を予測可能な例外に変えます。

本番環境では、ポーリングを一時的なネットワークエラーに対する Retry ポリシーでラップし、単一の requests.Session を再利用してください。多数のタスクを実行する場合は、wait をリクエストパスではなくワーカースレッドに移動してください。

よくある失敗のトラブルシューティング

ほとんどの統合問題はいくつかのカテゴリに分類できます。それぞれに具体的な確認方法があります。

認証エラー

401 または 403 は、キーが欠落している、期限切れ、または形式が誤っていることを意味します。Authorization ヘッダーが存在し、Bearer スキームを使用しており、環境変数が実行時に実際に設定されていること——シェル内だけでなく——を確認してください。

ペイロード形式の誤り

400 は通常、リクエストボディがスキーマに準拠していないことを意味します。JSON がパース可能であること、model が正確に flux-3-max/text-to-video であること、そしてリクエストが Content-Type: application/json を送信していることを検証してください。文字列を手動で構築するのではなく、JSON ライブラリを使用してシリアライズしてください。

無効なパラメータ値

ドキュメントの範囲を超えた再生時間、不明なフィールド名、または音声スイッチの型の誤りは、いずれも送信時に拒否を引き起こします。送信前にモデルのドキュメントに記載されたパラメータに従ってローカルで検証してください。

早すぎるポーリング

送信直後に繰り返しポーリングしてもタスクが早く完了することはありません。バックオフまたは固定間隔を使用し、タスクオブジェクトが queued ステータスを超えたことを通知するに任せてください。

未処理のタスク失敗

failed に達したタスクは、必ずしもリクエストにバグがあるわけではありません——コンテンツ拒否や内部エラーの可能性があります。エラーメッセージを読み、タスク識別子を記録し、修正したプロンプトで再試行するかエスカレーションするかを決定してください。

送信レスポンスを結果として扱う

コードが送信直後に動画 URL を期待している場合、それは誤動作します。最初のレスポンスはタスクであり、終端状態のみが出力を持ちます。これら6つのチェックが整えば、ほとんどの統合問題は解決できます。