HiAPI APIでwan2.7-video/text-to-videoモデルを呼び出す：実用的なショート動画ワークフロー

テキスト生成動画は単発の呼び出しではなく、パイプラインに組み込むべき理由

テキスト生成動画モデルを使う際に最もよくある間違いは、それを動き付きの画像生成器と見なしてしまうことです。プロンプトを1つ入力すれば、完成した動画が1本出力される——そう考えてしまいます。しかしショート動画はめったにそういうふうには動きません。見栄えのする15秒のクリップは、通常、複数の生成クリップ、1回の選別、そして1回の結合の結果であり、一度のまぐれ当たりのレンダリングではありません。

より役に立つメンタルモデルは、モデルをパイプラインの中のクリップ生成器として捉えることです。このパイプラインはおおよそ次のようになります：

1. プロンプト入力——明確な一瞬を描写するプロンプトを書きます：被写体、動作、シーン、そしてカメラがどう動くか。
2. クリップ生成——wan2.7-video/text-to-videoモデルがそのプロンプトに基づいて短いクリップを生成します。
3. 選別——生成されたクリップを確認し、それ自体で成立するものを残します。
4. 結合——残したクリップを結合し、トリミングし、編集して最終的なショート動画作品に仕上げます。

この視点には2つの帰結があります。第一に、生成された各クリップは単独で成立しなければなりません。あるクリップがより大きなシーケンスの一部としてしか意味をなさないなら、それは選別や並べ替えが難しいものになります。第二に、プロンプトがワークフローにおける主要な変数となり、統合コードはそうではなくなります。リクエストは一度書いたら、あとは何度もプロンプトのテキストを差し替えるだけです。

これこそが、早い段階からパイプライン思考で取り組む利点です。最初の呼び出しを単発のレンダリングとして設計してしまうと、後から選別や結合を組み込むには書き直しが必要になります。最初からクリップ生成器として設計しておけば、ワークフローの残りの部分は自然にその周りに育っていきます。

本記事で扱う内容

HiAPIベースのスタックにおいてこのモデルができること、1つの使えるクリップを中心にプロンプトをどう組み立てるか、カメラと動きの言語をどう表現するか、動作するリクエストの書き方、そして反復ループを通じて1回の有効な呼び出しを反復可能なプロセスに変える方法を明らかにします。

wan2.7-video/text-to-videoモデルがあなたのスタックで果たす役割

wan2.7-video/text-to-videoモデルはテキストプロンプトを受け取り、生成された動画クリップを返します。あなたのパイプラインが依存すべきはこの契約です：テキスト入力、クリップ出力。

HiAPIベースのスタックでは、モデルは単一の統合APIインターフェースの背後に位置します。あなたのアプリケーションはモデルと直接通信しません——HiAPIにリクエストを送り、HiAPIがモデル呼び出しを処理して生成されたクリップリソースを返します。これには統合の範囲を定める上でいくつかの実用的な意味があります：

• 1回の統合で何度も反復。 プロンプトが変わってもAPIインターフェースは安定したままです。リクエストは一度構築するだけで済みます。
• モデルは再利用可能な単位。 調整する変数はプロンプトのテキストであり、呼び出しの構造は定数です。
• 呼び出し周辺のすべてはあなたのスタックの責任。 アップロード、ストレージ、選別ロジック、結合、公開はすべてあなたの担当です——モデルはクリップの生成だけを担います。

範囲外とすべきこと

モデルが約束していない具体的な詳細を勝手に想定しないよう注意してください。推測に基づいて、フレームレート、解像度プリセット、単一クリップの最大長、正確なタイミング挙動などの仮定をパイプラインのロジックにハードコードしないでください。代わりに、返されたクリップは不透明なリソースとして扱うべきです：レスポンスからそのメタデータを読み取り、検証し、結合段階が各クリップの実際の長さに適応できるようにします。

この規律はショート動画の作業で特に重要です。ショート動画の出力は複数のクリップを結合して作られるため、実際のクリップ長に適応するパイプラインのほうが、固定のクリップ長を前提とするパイプラインよりはるかに堅牢です。

役割分担

明確な分担は次のとおりです：

• モデル側： プロンプトの解析、動きと動画クリップの生成。
• HiAPI側： 統合APIを通じた、認証付きのモデルアクセス。
• あなたの側： プロンプト設計、リクエスト処理、レスポンス検証、クリップの保存、選別、結合、納品。

この境界を守れば、ワークフローの残りの部分——プロンプト構造、カメラ表現、反復——は自然に整います。

ショート動画クリップのためのプロンプト構成

各クリップが単独で使えなければならないため、各プロンプトは単一の、それ自体で完結する一瞬を描写すべきです。信頼できる方法は、長い文章を書いて運任せにするのではなく、明確なモジュールでプロンプトを組み立てることです。

4つのモジュール

有効な構造の1つは被写体、動作、シーン、スタイルです：

• 被写体——画面の中に誰が、または何がいるか。具体的に：「赤いレインコートを着た自転車に乗る人」は「人」よりも良い。
• 動作——被写体がクリップの中で行うその一つのこと。単一の連続した動作に保つ。
• シーン——物事がどこで起こるか。必要なら光や天気も含める。
• スタイル——視覚的な処理方法：写実的、アニメーション、粒状感のある手持ち風、シネマティックなど。

たとえば、モジュール構造で書いたプロンプトはこうなります：赤いレインコートを着た自転車に乗る人が、夕暮れ時に濡れた街路を安定したペースで走り抜け、水たまりにネオンの反射が映り、写実的な手持ち風の見た目。

各クリップには動作を1つだけ書く

短いクリップには物語の弧を収める余地がありません。ある被写体が入ってきて、座り、コーヒーを注文して立ち去る、と描写すれば、モデルはその一部を圧縮するか捨てるしかなく、結果は予測不能になります。分割しましょう：入ってくるクリップ、座るクリップ、カウンターのクリップ。各クリップは選別でき、並べ替えができ、結合時にトリミングでき——しかもどれか一つが失敗しても個別に再生成しやすいのです。

モジュールを組み替えてバリエーションを生成する

各モジュールを独立したフィールドとして扱えば、低コストでバリエーションを生み出す方法が得られます。被写体とシーンを固定して動作を変える。動作を固定してスタイルを変える。こうすることで、うまく編集してつなげられる関連クリップのセットが生まれ、それがまさにショート動画の結合に必要なものです。コード内で小さなデータ構造からこれらのバリエーションをループ生成でき、プロンプトを一つずつ手書きする必要はありません。

プロンプトは簡潔に保つ

プロンプトに節が1つ増えるたびに、影響力を奪い合います。そのディテールがこの1つのクリップで画面に映る内容を変えないのであれば、削除しましょう。明確な4つのモジュールを持つ焦点の定まったプロンプトは、通常、5つのアイデアを積み重ねた長ったらしい雰囲気重視の記述に勝ります。

本当に読み取れるカメラと動きの表現を書く

曖昧な動きの動詞は曖昧な動きを生みます。プロンプトに「シーンがダイナミックに動く」や「興奮するカメラワーク」と書けば、モデルは空間的な指示を一切受け取れず、即興に頼るしかありません——そして即興のカメラ挙動は、選別段階でクリップが捨てられる最も一般的な原因です。

カメラの挙動は文字通りに書く

カメラマンに指示を出すように、具体的にカメラを描写しましょう。役立つ表現には次のようなものがあります：

• 「カメラが被写体に向かってゆっくりとプッシュインする」
• 「カメラが被写体を追って左にパンする」
• 「固定のロックオフショット」
• 「カメラが地面の高さからアイレベルまで上昇する」
• 「被写体の周りをゆっくりとオービットする」

これらの表現はいずれも方向と振幅（ゆっくり、固定、上昇）を同時に指定しており、それこそが読み取れる理由です。対照的に、「ダイナミックなカメラワーク」はどちらも指定していません。

被写体の動きとカメラの動きを分ける

これは2つの異なる指示であり、2つの異なるフレーズとして書くべきです。被写体は何かを行い、カメラは何かを行い、両者は独立に描写します。それらを1つの節に混ぜると——「カメラが走者が駆け抜けるのを追う」——どちらの要素が動きを駆動しているのかが不明瞭になります。

動きをクリップの長さに合わせる

短いクリップには複雑なカメラの動きは収まりません。同じ2秒のクリップでプッシュイン、パン、オービットを同時に行えば、圧縮されてぼやけるか、完全に捨てられるかのどちらかです。各クリップでは1つのカメラ挙動だけを選び、振幅も控えめに保ちましょう。長く変化し続けるカメラの動きが必要なら、それは結合段階の仕事です：カメラ位置を徐々に変えた複数のクリップを生成し、それらを編集でつなげます。

空間的なアンカーを使う

モデルは相対的な位置をよく理解します。「前景に」「被写体の後ろに」「左側から」「画面の右上に向かって」といったフレーズが参照点を与えてくれます。被写体にアンカーを1つ、カメラにアンカーを1つ与えるだけで、形容詞を積み重ねるよりもカメラが安定することがよくあります。

書いたら読み返す

リクエストを送る前に簡単なチェックをしましょう：カメラを持った人に指示を出すように、動きのフレーズを読み返してみてください。その人が質問を返してくるなら、プロンプトにはより具体的な答えが必要です。

動作するHiAPIテキスト生成動画クリップのリクエスト

このセクションではリクエストの書き方をエンドツーエンドで解説します。目標は、一度保存して再利用するテンプレートを手に入れることで、実行のたびにプロンプトのテキストだけを変えるだけで済むようにすることです。

ステップ1：認証

すべての呼び出しは、API認証情報を使ってHiAPI経由で行います。キーはソースコードではなく環境変数に置きましょう：

export HIAPI_API_KEY="your_key_here"

ステップ2：生成リクエストを送る

リクエストでモデルを指定し、プロンプトを渡します。curlを使った最小限の書き方は次のとおりです：

curl -X POST "https://api.hiapi.ai/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan2.7-video/text-to-video",
    "prompt": "赤いレインコートを着た自転車に乗る人が、夕暮れ時に濡れた街路を安定したペースで走り抜け、水たまりにネオンの反射が映り、カメラがゆっくりとプッシュインし、写実的な手持ち風の見た目"
  }'

プロンプトが4つのモジュールと明確なカメラ指示をどのように担っているかに注目してください。これが前述の構造であり、それがシリアライズされただけです。

ステップ3：レスポンスを処理する

レスポンスは生成されたクリップリソースへの参照を返します。レスポンスに依存する前に、検証すべきデータとして扱いましょう：

• レスポンスボディをJSONとして解析し、結果を読む前にエラーフィールドがないか確認する。
• クリップ参照が存在することを確認する。存在しない場合は完全なレスポンスを記録して停止し、空の値で続行しない。
• レスポンスからクリップのメタデータを読み取り、そのクリップを生成したプロンプトと一緒に記録する——これが後の反復ループの基礎となる。
• クリップを自分のストレージにダウンロードまたはストリーミングする。永続化はあなたのパイプラインの責任だから。

ステップ4：関数にカプセル化する

実際のワークフローでは、プロンプト文字列を受け取ってクリップ参照とメタデータを返す小さな関数にリクエストを移しましょう。モデル名、リクエストヘッダー、エラー処理はすべて関数の内部に置きます。それ以降、各実験は統合作業ではなくプロンプト1行の変更で済みます。

import os, requests

def generate_clip(prompt: str) -> dict:
    resp = requests.post(
        "https://api.hiapi.ai/v1/video/generations",
        headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
        json={"model": "wan2.7-video/text-to-video", "prompt": prompt},
        timeout=120,
    )
    resp.raise_for_status()
    data = resp.json()
    if not data.get("clip"):
        raise ValueError(f"No clip in response: {data}")
    return data

この関数はパイプラインにおける再利用可能な単位です。その後のすべてはこの上に築かれます。

ステップ5：結合前に検証する

クリップが結合段階に入る前に、ファイルがきれいにダウンロードできるか、そしてその長さが結合ステップで想定して扱える範囲内かを確認しましょう。公開時に破損したクリップに気づくのではなく、早い段階で拒否するのです。

反復：1つの良いクリップから反復可能なショート動画ワークフローへ

リクエストが動くようになると、面白い作業が始まります：1つの良いクリップを、ショート動画の出力を確実に生み出すプロセスに変えることです。

反復ループ

このループには3つの段階があり、繰り返し続けます：

1. プロンプトを変える。 一度に1つのモジュールだけを変える——動作、カメラフレーズ、スタイル。複数を一度に変えると、どの変更が効いたのか判断できません。
2. クリップを選別する。 生成された一群のクリップを確認し、使えるものを残す。選別の判断を記録しましょう。「プッシュインは有効、オービットは速すぎる」といったメモは、クリップそのものよりも価値があります。
3. 結合する。 残したクリップをつなげ、必要な長さにトリミングし、各セグメントがきれいにつながるか確認する。

結合の出力は次のプロンプト変更のラウンドにフィードバックされます。2つのクリップがつながらないなら、それは情報になります——プロンプトのどの点（被写体のフレーミング、光、動きの方向）を一貫させるべきかの手がかりです。

プロンプトライブラリを構築する

残したクリップを生み出したすべてのプロンプトを、そのクリップ参照とメモと一緒に保存しましょう。数ラウンドを経ると、これは小さなパターンライブラリになり、再結合できます：実証済みの被写体記述、実証済みのカメラフレーズ、実証済みのスタイルモジュール。こうすることで新しい動画は白紙のプロンプトからではなく、既知の良い部品から組み立てられます。

データ構造から一括生成する

リクエスト関数がプロンプト文字列を受け取るので、バリエーションの生成はリストや小さな設定オブジェクトのループになります。被写体とシーンを一度定義し、動作リストとカメラフレーズリストをループして候補のセットを生成します。これこそがパイプライン視点の見返りです：モデルは定数、プロンプトは変数、そしてあなたのコードは変化を列挙するだけでよいのです。

選別を低コストに保つ

生成されたすべてのクリップを完全に見る必要はありません。事前に簡単な却下基準を定義しましょう——被写体が違う、動きがない、フレーミングが使えない——そして素早く捨てる。確認の時間はエッジケース、つまりトリミングすれば使えるかもしれないクリップに費やしましょう。

ワークフローをバージョン管理する

残した各クリップについて、プロンプト、モデル名、レスポンスメタデータを一緒に保存しましょう。チャンネルのビジュアルスタイルが変わったとき、現在のスタイルがどのプロンプトパターンから生じたかを正確にたどれ、当てずっぽうではなく既知のベースラインから調整できます。

よくある落とし穴と回避策

テキスト生成動画パイプラインでは、いくつかの失敗パターンが繰り返し現れます。それぞれに直接的な修正方法があります。

曖昧な動きの動詞

症状： 返されたクリップのカメラの動きがランダムに見える、または被写体がほとんど動かない。 修正： 抽象的な動きの言葉を、文字通りで方向のある指示に置き換える。各クリップで1つのカメラ挙動と1つの被写体動作を指定し、それぞれに振幅（ゆっくり、安定、固定）を添える。

プロンプトの詰め込みすぎ

症状： 記述の一部が出力から欠落する、または結果が複数のアイデア間の妥協のように見える。 修正： 各クリップで動作を1つだけに強制し、画面に映る内容を変えないディテールを削除する。複数カットのアイデアは独立したクリップに分割し、順序付けは結合段階に任せる。

レスポンス検証の省略

症状： 失敗した、または不正な形式のレスポンスがストレージや結合段階に流れ込み、公開時に初めて気づく。 修正： 呼び出しのたびに直ちにエラーとクリップ参照の有無を確認し、失敗時は完全なレスポンスを記録し、リソースが選別に入る前に検証する。

固定のクリップ属性の仮定

症状： 返されたクリップの長さや形式が想定と異なると、結合ロジックが破綻する。 修正： レスポンスからメタデータを読み取り、結合時に適応させる。クリップの長さをパイプラインにハードコードしない。

一度に太多くの変数を変える

症状： どのプロンプト変更が出力を改善または破壊したのか判断できない。 修正： 各反復でモジュールを1つだけ変え、メモを残す。ここでのプロンプトエンジニアリングは書き直しではなく実験ループである。

API呼び出しを製品全体と見なす

症状： リクエストは動くが信頼できる出力がない。選別と結合が構築されていないため。 修正： 生成は1つの段階にすぎないことを忘れない。クリップの確認、保存、結合に本気で取り組む時間を確保する——ショート動画の品質は実質的にそこで決まる。

リクエストを再利用可能な関数に保存し、プロンプトのテキストを反復すれば、上記の落とし穴のほとんどは自然に消えます。