HiAPI API の flux-3-max/text-to-video を使ってショート動画を構築する

ショート動画がプロンプト編成の問題である理由

テキスト生成動画で失敗するチームのほとんどは、同じ理由でつまずきます。シーン全体を説明する巨大なプロンプトを1本書き、モデルが完成した30秒の動画を返してくれると期待するのです。生成はそういうふうには動きません。モデルは呼び出しごとに1つの連続したショットしか生成せず、各呼び出しは被写体、動作、構図、音に関する小さく自己完結した意思決定なのです。

実際に通用するメンタルモデルは編成です。あなたは動画にプロンプトを出すのではなく、一連のショットを演出し、それらを組み立てるのです。1本のショート動画作品——製品予告、ソーシャルのフック、ナレーション解説——は通常4〜8つのショットで構成されます。各ショットは1つの役割だけを担います。確立、提示、転換、締めくくり。この分解を受け入れた瞬間、APIはもはやスロットマシンではなく、あなたが制御するパイプラインの中のレンダリングステップになります。

これが重要なのは、テキスト生成動画の失敗モードの大半が品質の失敗ではなく連続性の失敗だからです。個々のショットは美しく見えても、次のショットでキャラクターが違い、光の方向が違い、あるいはカメラが突然漂流してしまうなら、そのショットは使えません。こうした問題はリクエストを送る前——巨大なプロンプトに形容詞を足すことではなく、ショットをどう計画し記述するかによって——解決できます。

本ガイドの残りでは、HiAPI経由でflux-3-max/text-to-videoを呼び出しながら、このワークフローをエンドツーエンドで案内します。台本をショットに分割し、ショットごとのプロンプトを書き、カメラワークを制御可能な次元として扱い、ネイティブ音声で別々の音声処理工程を省き、すべてを小さく再現可能なリクエストループに収めます。

API を呼び出す前にショットを計画する

コードを書く前に、台本をショットリストに変換します。ショットリストは純粋なデータ構造です。生成呼び出し1回につき1エントリ、各エントリには明確な目的があります。次の構造は中間表現として適しています。

[
  {
    "id": "s1",
    "role": "establish",
    "subject": "ceramic pour-over coffee dripper on a wooden counter",
    "framing": "medium close-up, three-quarter angle",
    "durationIntent": "short",
    "camera": "slow push in",
    "audio": "quiet room tone, soft steam"
  },
  {
    "id": "s2",
    "role": "demonstrate",
    "subject": "hot water spiraling over coffee grounds",
    "framing": "tight overhead macro",
    "durationIntent": "short",
    "camera": "locked off",
    "audio": "water pouring, gentle hiss"
  }
]

後での再試行を節約する計画ルールがいくつかあります。

• 1ショットにつき1つのアイデア。 ショットの説明に「そして」が含まれるなら、分割してください。モデルは一連のビートよりも、単一の連続した動作のほうがはるかに得意です。
• 秒数ではなく時間の意図を表現する。 ショットが素早い切り替えなのか、より長い静止なのかを決め、意図として表現します。正確なタイミングは編集・結合の段階に属し、そこではフレーム単位の精密な制御が得られます。
• 構図の語彙を早期に固める。 wide、medium、close-up、overhead、low angleといった用語を選び、各ショットでそのまま再利用します。一貫した語彙はより一貫した結果を生みます。
• 連続性のアンカーを計画する。 何が変わらないかを決めます。キャラクターの説明、衣装、色調、時刻、光の方向。これらを一度共有プレフィックスとして書き、すべてのプロンプトで再利用します。
• レビューでは順序が重要。 台本の順序で生成すれば、クリップを孤立した断片としてではなく最終的な再生順でレビューできます。

ショットリストが存在すれば、API呼び出しは機械的になります。これこそが望ましいことであり、呼び出しを再試行可能かつ再現可能にしてくれます。

flux-3-max/text-to-video 向けのショットごとのプロンプトを書く

優れたショットごとのプロンプトは構造化されており、会話的ではありません。長い自由形式の文字列を書くのではなく、少数のラベル付きセクションで各プロンプトを構成します。これによりプロンプトは差分比較可能で再利用可能になり、ある単一の要素がうまくいかないときに調整しやすくなります。

5セクション構成

1. 被写体 —— 誰または何か。決めた連続性の詳細（外見、衣装、製品の特徴）を含めます。
2. 動作 —— 1つの連続した動きや状態を現在時制で記述します。
3. 環境 —— 場所、時刻、光の質感、色調。
4. カメラ —— 構図と動き。固定した語彙を使います。次のセクションで詳しく説明します。
5. 音声 —— このショットの環境音とフォーリーの意図。

固定した順序で組み合わせ、自分自身のデバッグも一貫させます。

CONTINUITY = (
    "a minimalist ceramic pour-over coffee dripper, matte white, "
    "on a warm oak counter, soft morning window light from the left, "
    "muted natural palette"
)

def shot_prompt(subject, action, setting, camera, audio):
    return (
        f"{subject}. {action}. {setting}. "
        f"Camera: {camera}. Audio: {audio}."
    )

prompt = shot_prompt(
    subject=f"{CONTINUITY}",
    action="steam rising steadily as water slowly blooms the coffee grounds",
    setting="kitchen counter at dawn, shallow depth of field",
    camera="medium close-up, slow push in, no shake",
    audio="quiet room tone, soft water pour, faint steam hiss",
)

ショットの視覚的一貫性を保つ

最も効果の高い単一の習慣は、共有の連続性ブロックです。これを各被写体セクションの先頭に置き、シーケンス全体のすべてのショットで一定に保ちます。あるショットが視覚的にずれたときは、二分探索で原因を特定できます。連続性ブロックの問題か、ショット固有の動作の問題か？

ずれを減らすもう2つの習慣があります。

• 矛盾する形容詞を避ける。 「シネマティック・ドキュメンタリー・ハンドヘルド・スタティック」は3つの衝突する指示です。1つを選びましょう。
• 光は一度だけ記述する。 連続性ブロックが左からの朝光と書いているなら、後のショットで天井の蛍光灯を持ち込まないでください。その切り替えが意図的な場合を除いて。

プロンプトに書くべきでないもの

アスペクト比、出力長、その他の技術パラメータはテキスト記述から外し、APIが公開している場合はリクエストパラメータとして渡します。テキスト記述はショットが何であるかを語り、パラメータはどう届けられるかを語ります。両者を混ぜると、どちらも変更しにくくなります。

カメラワークを制御する

カメラワークは偶然に委ねられやすい次元であり、シーケンスが演出されていると感じられるかどうかに最も影響する次元でもあります。指定しなければ、モデルは何らかの方法でカメラを動かします。未指定の動きは漂流として現れ、その漂流こそが生成素材を偶然撮られたように見せる原因です。

動きを小さな閉じた語彙として扱う

ショットごとにカメラ言語を即興で作らないでください。小さな動きのセットを定義して再利用します。

• 固定カメラ —— 動かない。製品ディテールやクローズアップに最も安全な選択。
• プッシュイン / プルアウト —— 被写体に近づく、または遠ざかる。強調と明示に適しています。
• 左パン / 右パン —— 水平回転。空間を確立するのに使います。
• ティルトアップ / ティルトダウン —— 垂直回転。慎重に使ってください。非常にドラマチックに読まれます。
• トラッキング —— 被写体とともに動く。アンカーとなる明確に動く被写体が必要です。

カメラセクションに書き、残りの動きを抑制する否定指示を続けます。Camera: slow push in, no shake, no handheld drift.

否定句は重要です。「プッシュイン」だけでは揺れを加える余地をモデルに残しますが、「プッシュイン、揺れなし」は範囲を狭めます。

動きをショットの役割に奉仕させる

動きは編集に奉仕すべきです。実用的な対応関係：

• 確立ショット —— 明確な動き1つ（ゆっくりしたプッシュインや穏やかなパン）で、視線に着地点を与えます。
• ディテールショット —— 固定カメラ。ディテール自体が視覚的に情報密度が高く、動きはそれと競合します。
• トランジション —— 隣接するショットで一貫した動き（両方プッシュイン、両方同じ方向へのパン）を使えば、トランジションエフェクトなしでも切り替えが意図的に感じられます。
• ヒーローショット —— 意図的な動きを1つだけ。2つを組み合わせないでください。

1ショットにつき動きは1つ

動きの組み合わせ（「右にパンしながらプッシュインし、ティルトアップ」）は濁った結果を生みます。あるビートが複雑なカメラワークを必要とするなら、2つのショットに分割してください。結合段階でそれらをつなげられ、切り替えに対してフレーム単位の制御も保てます。

シーケンス内の動きの一貫性

作品全体の主導的な動きを事前に決めます。たとえば「すべてのショットをゆっくりプッシュイン」とし、効果が必要なときだけ逸脱します。動きの方向が一貫したシーケンスは作者の意図を感じさせ、動きがランダムなシーケンスは生成されたように感じさせます。

パイプラインでネイティブ音声を使う

ネイティブ音声生成はショート動画パイプラインのアーキテクチャを変えます。従来のフローでは、まず無音動画を生成し、次に別の音声処理工程——テキスト生成音声モデルか、ライセンスされたフォーリーや音楽ライブラリ——を実行し、エディタで両者を揃えます。各段階は別のサービス、別の認証情報、別の失敗モード、そしてタイミングがずれる可能性のある別の場所です。

動画モデルが音声をインラインで生成するとき、音と映像は同じ推論ステップで生成されるため、画面上で起きていることと自然に揃います。水が注がれる瞬間、注水音は注水動作と一致します。これによりアライメント作業はほぼ完全に消えます。

2つのパイプライン、1つの違い

Separate audio stage:            Native audio:
  shot -> video (silent)           shot -> video + audio
       -> audio generation              -> assemble
       -> alignment / mixing
       -> assemble

実用的な利点は可動部品が少ないことです。実用的な制約は、音を後から足すのではなくプロンプト内で計画する必要があることです。

音を中心にショットを計画する

音声は生成の一部なので、後付けではなくショットの一部として書きます。

• 主要な音を名指しする。 Audio: water pouring, gentle hissはAudio: pleasant kitchen soundsより優れています。
• 疎に保つ。 ショットごとに1〜2つの明確な要素。音声記述を重ねると往々にして濁ります。
• 音楽は意識的に決める。 エディタで作品全体に音楽ベッドを敷く予定なら、ショットの音声は環境音だけにしておき、音楽トラックと衝突しないようにします。
• 音の連続性を考慮する。 視覚的連続性と同様、切り替えをまたぐ音声の連続性も有効です。隣接するショットで同じルームトーンが流れれば、シーケンスは同じ場所で起きているように感じられます。

エディタが依然として勝つところ

ネイティブ音声はエディタを置き換えません。置き換えるのはアライメントのステップです。最終的なラウドネス正規化は依然として必要であり、音楽を使うなら、セリフやフォーリーをベッドの下に下げるミキシング工程も必要です。これらのためにパイプライン内で予算を確保してください。ただし別の生成段階を使う場合よりはるかに少ない予算で済みます。

実行可能なリクエストと組み立てフロー

ショットリストとプロンプトビルダーがあれば、リクエスト層は薄くなります。重要な決定は、モデルをどう呼ぶか、順序と再試行をどう扱うか、結果をどう結合に渡すかです。

編成ループ

import time

SHOTS = [
    # your planned shot list from the earlier step
]

def generate_shot(shot, attempt=0):
    payload = {
        "model": "flux-3-max/text-to-video",
        "prompt": build_prompt(shot),
        # pass delivery parameters here, not in the prose:
        # aspect ratio, length, etc. per the API reference
    }
    try:
        return client.generate(payload)
    except TransientError:
        if attempt >= 3:
            raise
        time.sleep(2 ** attempt)
        return generate_shot(shot, attempt + 1)

def run_sequence(shots):
    results = {}
    for shot in shots:
        results[shot["id"]] = generate_shot(shot)
    return [results[s["id"]] for s in shots]

このループを単なるデモではなく本番で安全にする3つのポイント：

• 順序付きの反復。 台本の順序で生成すれば、部分的な失敗はレビュー可能なプレフィックスを残し、欠けたショットだけを再実行するのも簡単です。
• キーで保存された結果。 出力はリストの位置ではなくショットIDで保存します。3番目のショットが失敗して再生成された場合、追記ではなくキーで上書きします。
• 上限付きの再試行とバックオフ。 一時的な失敗はどの生成APIでも普通のことです。再試行回数を制限し、1つの悪いショットがジョブ全体を止めないようにします。

結合への引き渡し

生成ループはマニフェスト——出力参照付きのショットリスト——を生成して終わるべきです。結合はそのマニフェストを消費する別ステップです。各クリップを意図した長さにトリムし、トランジションを適用し、音楽ベッドを敷き、ラウドネスを正規化します。

{
  "sequence": [
    {"id": "s1", "clip": "out/s1.mp4", "trim": "keep_first_portion"},
    {"id": "s2", "clip": "out/s2.mp4", "trim": "keep_first_portion"}
  ],
  "audioStrategy": "native_bed_plus_music"
}

結合と生成を分離することで、パイプライン全体が再現可能になります。あるショットを再生成し、マニフェストに入れ、他の何も触れずに最終カットを再レンダリングできます。

本番チェックリストとよくある落とし穴

ショート動画パイプラインは、退屈な部分が退屈になったときに信頼できるものになります。量を拡大する前に、これらのチェックを実行してください。

一貫性

• 連続性ブロックがシーケンスのすべてのショットで完全に一致している。
• ショットの語彙が閉じており再利用され、即興で作られていない。
• 光の方向と色調が一度だけ宣言され、後で矛盾しない。
• ショットを順序通りにレビューする——クリップを孤立して見ると連続性の問題は見えない。

再試行と冪等性

• 結果はショットIDでキー付けされ、再生成が重複ではなく上書きになる。
• 再試行は上限付きでバックオフを使う。恒久的に失敗するショットは静かに失敗するのではなく、大きな音で失敗すべき。
• ショットマニフェストが生成内容の唯一の真実の source である——出力とともに永続化する。

コスト管理

生成はモデルが生み出す作業量に応じて課金されるため、主なレバーは生成するショットの数と再生成する回数です。実用的な制御手段：生成前にショットリストを固定し、残りをレンダリングする前に各シーケンスの代表的なショットをレビューし、すでに承認されたショットを投機的に再抽選するのを避けます。生産量を計画する際は、ウェブサイトの価格パネルで最新の価格を確認してください。

出力レビュー

• 各シーケンスをクリップごとではなく、実際の再生速度でエンドツーエンドで視聴する。
• 映像と照らし合わせて音声を確認する。音はその瞬間に合っているか？
• 特に最初の2秒をチェックする。ショート動画の注意力はそこで勝ち取られるか失われる。
• 既知の良好な参照プロンプトを小さなセットとして維持し、品質が落ちたように見えるときは新しい出力と比較する。

よくある落とし穴

• 巨大なプロンプト。 シーン全体を説明する1本のプロンプトは、長く焦点のぼけたショットを生みます。分割してください。
• テキスト記述に長さを書く。 タイミングはプロンプトテキストではなく編集段階で表現してください。
• ランダムなカメラワーク。 未指定の動きは漂流します。動きを指定し、残りを抑制してください。
• 音声を独立した製品上の決定として扱う。 音はショット内で計画し、エディタでミックスします。

本ガイドのワークフロー——ショットを計画し、プロンプトを構造化し、カメラワークを制御し、ネイティブ音声を使い、マニフェストで編成する——は、flux-3-max/text-to-videoを予測不能な生成器から、あなたが所有するパイプラインの中の信頼できるレンダリングステップへと変えます。