HiAPI API 経由で flux-3-video を呼び出す方法：curl、Python、そして実際に動作するリクエスト例

flux-3-video が API 経由で提供する機能

最初の行のコードを書く前に、flux-3-video モデルが HiAPI API 経由で一体何ができるのかを把握しておくと役立ちます。このエンドポイント群は、同一のリクエスト構造を共有する 2 つの呼び出しモードに加え、ユースケースに応じて有効化したり無視したりできるオプションの音声機能を備えています。

2 つの呼び出しモード

• テキストからの動画生成——テキストプロンプトを送信すると、新しく生成された動画クリップを受け取ります。アイデアだけがあり、動き・構図・リズムをモデルに生成させたい場合にこのモードを使います。
• 動画の続き生成——既存の動画クリップ（またはその参照）と指示を送信すると、モデルがそれを前方に延長します。既に素材があり、目に見える継ぎ目なくコンテンツを増やしたい場合にこのモードを使います。

ネイティブ音声

このモデルは動画生成と同時にネイティブ音声を出力することもでき、同じリクエストペイロード内のオプションパラメータで制御します。これらのパラメータはオプションであるため、動画のみのワークフローではまったく考慮する必要がありません。音声フィールドを省略するだけで、リクエストはそれらがない場合とまったく同じ動作になります。

本ガイドの以降の内容が依拠する中心的なメンタルモデルはこれです：これは 2 つの独立した API でも、2 つの別々のチュートリアルでもありません。同じ 1 つのリクエストの 2 つの形態であり、共有された骨格を一度理解すれば、両者の切り替えは入力の一部を差し替えるだけになります。それ以外のすべて——認証情報、リクエストヘッダー、モデル識別子、レスポンス処理——は変わりません。

この設計は意図的なものです。つまり、認証コード、エラー処理、リトライロジック、レスポンス解析を一度書けば、両方のモードで再利用でき、後から音声を追加しても書き直しを強いられることはありません。

認証、エンドポイント、リクエスト構造の解剖

flux-3-video へのすべての呼び出しは同じ骨格に従います。一度マスターすれば、2 つの呼び出しモードは同じテーマのバリエーションにすぎなくなります。

認証情報

HiAPI は API key でリクエストを認証します。通常は bearer token の形でリクエストヘッダーを通じて渡します。キーをソースコードに書き込まないでください——環境変数やシークレットマネージャーから読み込み、バージョン管理システムに決して入らないようにしてください：

export HIAPI_API_KEY="your-key-here"

エンドポイントとモデル識別子

呼び出しは HiAPI API のベース URL に送信し、ペイロードで識別子 flux-3-video を指定してモデルを明示します。モデル名を URL にハードコードするのではなくリクエストボディに書くことで、同じクライアントコードを後日 1 行変更するだけで別のモデルに向けられます。

共有されるペイロード構造

どちらのモードでも、ペイロードは JSON オブジェクトであり、概念的には 3 つの部分で構成されます：

• model フィールド——常に flux-3-video。
• モードを定義する入力——テキストからの動画生成ではプロンプト、続き生成ではソース動画クリップとプロンプト。2 つのモード間で実質的に変わるのはこの部分だけです。
• オプションの修飾項目——音声パラメータやその他の調整項目。これらを省略すればデフォルトの動作になります。

リクエストの擬似構造は次のとおりです：

{
  "model": "flux-3-video",
  "input": {
    "prompt": "..."
  }
}

全体の考え方はこれだけです：モデル識別子が 1 つ、モード固有のフィールドを格納するネストされた input オブジェクトが 1 つ、そして必要に応じてのみ追加されるオプションキー。以降の章では各モードの具体的な詳細を 1 つずつ説明します。

テキストからの動画生成：最初の実用的な curl リクエスト

以下はプロンプトから動画を生成する、最小限でありながら完全なリクエストです。HIAPI_API_KEY がシェルでエクスポート済みであることを前提としています。

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "A slow dolly shot through a rain-soaked neon alley at night, reflections on wet asphalt, cinematic"
    }
  }'

各フィールドの役割

• Authorization——bearer token を保持します。これがないと、生成が始まる前にリクエストは拒否されます。
• Content-Type: application/json——リクエストボディは JSON なので、これを宣言してください。これを忘れると、紛らわしい 4xx レスポンスのよくある原因になります。
• model——flux-3-video をターゲットモデルとして識別します。
• input.prompt——テキストからの動画生成モードで唯一必須のクリエイティブ入力です。ショットの説明を書くように記述してください：被写体、動き、構図、光、雰囲気。

注力する価値のあるプロンプト作成のポイント

プロンプトはこのモードで唯一のクリエイティブなコントロールであるため、その品質が結果を直接左右します。役立つ習慣は 2 つあります：

• 内容だけでなく動きを描写する。「A dolly shot through…」（ドリーショットが……を通り抜ける）はモデルにアニメーション化可能なカメラの挙動を与えますが、静的な説明ではモデルは何もできません。
• 具体的に保つ。具体的な光や質感の手がかり（「wet asphalt」「neon reflections」）は、抽象的な形容詞よりも一貫性のある映像を生み出す傾向があります。

このリクエストを実行してレスポンスを確認すれば、キー、ヘッダー、基本ペイロードを検証できたことになります——これが以降のすべての基盤です。

動画の続き生成：既存のクリップを延長する

続き生成は前節の骨格を再利用しますが、input オブジェクトの形が変わります。プロンプトは単独で存在するのではなく、モデルが延長すべきソースクリップとペアになります。

curl -X POST "$HIAPI_BASE_URL/v1/generate" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-3-video",
    "input": {
      "prompt": "Continue the camera push forward as the alley opens into a crowded market",
      "video": "<reference-to-existing-clip>"
    }
  }'

テキストからの動画生成に対する変更点

• 動画入力が現れます。モデルがそれを基に構築すべき既存のクリップを提供します。これが 2 つのモード間の決定的な違いです。
• プロンプトは生成的なものではなく、方向づけるものになります。テキストからの動画生成ではシーン全体を記述しますが、ここでは次に何が起こるかを記述します。カメラがどこへ向かうか、何が画面に入るか、シーンがどう展開するかを続きの指示として書いてください。
• それ以外はすべて同じです。同じエンドポイント、同じリクエストヘッダー、同じモデル識別子、同じ input ラッパー。クライアントコードはペイロードを構築するときに初めて分岐するだけで済みます。

継ぎ目での一貫性を保つ

モデルは目に見えるカットを避けるために、ソースクリップの見た目に合わせる必要があります。簡潔で具体的かつ既存のスタイルを保つ指示のほうが、シーンを再構想する長い説明よりも効果的なことがよくあります。最初の続き生成がずれた場合は、他の場所に詳細を追加するのではなく、プロンプトをソース映像の実際の内容に近づけてください。

クリップ参照に関する注記

ソースクリップの正確な入力規約は、HiAPI 上のこのモデルの入力スキーマによって定義されます。フィールド形式を推測するのではなく、そのスキーマに従ってください——それが続き生成の入力として何を受け付けるかの権威ある情報源です。

ネイティブ音声パラメータを追加する

ネイティブ音声は、オプションの修飾項目パターンが真価を発揮する場面です。音声パラメータは他のフィールドと同じ input オブジェクト内にあり、オプションであるため、前の 2 節のリクエストはそれらなしでも引き続き有効です。

配置場所

音声設定は input の内部にあり、prompt や（続き生成モードでは）video と並びます。概念的には：

{
  "model": "flux-3-video",
  "input": {
    "prompt": "...",
    "audio": {
      "enabled": true
    }
  }
}

動画のみのワークフローを安全に保つ

ここで重要な規律はシンプルです：音声ブロックは純粋に付加的なものとして扱う。

• 音声フィールドを明示的に「オフ」の値に設定しない——省略すれば十分です。ブロックが存在しないほうが、明示的に無効化するよりもクリーンで、将来のスキーマ変更と衝突しにくくなります。
• ペイロードを段階的に構築する。最小限のリクエストボディから始め、ユーザーが実際に音声を要求したコードパスでのみ audio キーを追加します。これにより、デフォルトのパスが動画のみの例と完全に一致します。
• 音声を本番環境に組み込む前に、スキーマを参照して正確なフラグ名と許容値を確認する。パラメータの命名は HiAPI 上のこのモデルの入力スキーマによって定義されます。上記のブロック名は配置場所を示すだけで、フィールドの綴りを保証するものではありません。

いつ有効化するか

成果物が完成した自己完結型の動画クリップである場合——ソーシャルメディアコンテンツ、プレゼンテーション、短いナラティブ作品——には音声を有効化します。下流で独自のBGMやナレーションを別途重ねる場合はオフのままにしてください。最終的に破棄する音声を生成することは、パイプライン内で計算資源を浪費するだけです。

音声は他のすべてと同じ 1 つのペイロードに載るため、別個の呼び出しも、2 つ目の認証情報も、レスポンスが返す内容を読み取る以外の追加のレスポンス処理分岐も必要ありません。

同じリクエストを Python で書く

curl 呼び出しを Python に書き換えるのは機械的な作業です。なぜならリクエスト構造が完全に同じだからです。以下の例は標準ライブラリのみを使用しているため、どの環境でも動作します。requests や httpx を好む場合も、その構造はそのまま対応できます。

import json
import os
import urllib.request

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

def generate_video(prompt, video=None, audio=False):
    input_block = {"prompt": prompt}

    # Continuation mode: attach the source clip.
    if video is not None:
        input_block["video"] = video

    # Audio is strictly additive and omitted by default.
    if audio:
        input_block["audio"] = {"enabled": True}

    payload = {"model": "flux-3-video", "input": input_block}

    request = urllib.request.Request(
        f"{BASE_URL}/v1/generate",
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request) as response:
        return json.loads(response.read().decode("utf-8"))


if __name__ == "__main__":
    # Text-to-video
    result = generate_video(
        "A slow dolly shot through a rain-soaked neon alley at night"
    )
    print(result)

    # Video continuation with native audio
    result = generate_video(
        "Continue the camera push forward as the alley opens into a market",
        video="<reference-to-existing-clip>",
        audio=True,
    )
    print(result)

なぜこのように構成するのか

• 1 つの関数で 2 つのモード。video パラメータはオプションです。None のとき、この関数はテキストからの動画生成リクエストを生成します。設定されているとき、同じ関数が続き生成リクエストを生成します。別個のクライアントも、重複したリクエストヘッダーもありません。
• 音声は明示的に有効化する必要がある。audio フラグはデフォルトで False であるため、明示的に要求されない限り音声ブロックは決して追加されません——これが前述のパターンそのものです。
• キーは環境から取得する。API key は HIAPI_API_KEY から読み込まれ、決してハードコードされません。

改修する際は、print 呼び出しをパイプラインに必要な処理に置き換えるだけです——レスポンスをマニフェストに書き込む、後続タスクをキューに入れる、キューに通知するなど。リクエストロジック自体を変更する必要はありません。

トラブルシューティングと本番環境チェックリスト

呼び出しが失敗したときは、次のリストを順番に確認してください——ほとんどの問題をカバーできます。

診断チェックリスト

• 401 または認証エラー——HIAPI_API_KEY は実際にコードを実行しているシェルまたはプロセスでエクスポートされていますか？あるターミナルで設定したキーは cron ジョブには引き継がれません。
• 415 または予期しないパースエラー——Content-Type: application/json はありますか？これを忘れるのが最も典型的なサイレント失敗です。
• 続き生成の呼び出しが 4xx を返す——ペイロードはモデルの入力スキーマが期待する形式でソースクリップを含んでいますか？形式が誤ったクリップ参照は生成が始まる前に失敗します。
• 出力に音声がない——audio ブロックは実際にペイロードに入りましたか？デバッグ時はシリアライズ後のリクエストボディをログに記録してください。辞書を構築したのにキーの追加を忘れることはよくあります。
• input が空または切り詰められている——実際に送信している正確な JSON を出力してください。「奇妙な」失敗のほとんどは、実際に送信されたリクエストボディを自分の目で確認すれば解決します。

本番環境に投入する前に

• キーを決してハードコードしない。常に環境変数またはシークレットマネージャーを使用してください。
• リクエストボディとレスポンスボディの両方をログに記録する——少なくともステージング環境では。正確なペイロードなしで失敗を再現するのは当て推量にすぎません。
• オプションフィールドはオプションとして扱う。ペイロードを段階的に構築する——まず最小限のリクエストボディ、次に video を追加し、最後に必要な場合にのみ audio を追加します。これにより、デフォルトのパスをドキュメントの例と一致させられます。
• 自分のコード内でモード選択を明示的に見えるように保つ。オプションの video パラメータを持つ関数は問題ありませんが、ブール値を 3 層の奥深くに埋め込むのは良くありません。
• フィールドを追加するたびに、HiAPI 上のこのモデルの入力スキーマを再確認する。それがパラメータ名と許容形式の権威ある参照であり、どのチュートリアルよりも最新です。

核心となる要点を改めて強調します：テキストからの動画生成、続き生成、ネイティブ音声は、同じリクエスト形態の 3 つのバリエーションです。骨格を一度マスターすれば、新しい機能はすべて書き直しではなく付加的な変更にすぎません。楽しい開発を。