Grok テキスト・トゥ・ビデオ API：hiapi 経由で grok-imagine ビデオモデルを呼び出す

なぜ集約 API 経由で Grok ビデオ生成を呼び出すのか

ビデオ生成は単一モデルの問題であることはほとんどありません。ひとつのアイデアから出発すると、すぐに草稿用のより安価なバリアント、最終稿用のより高い忠実度のモデル、そしてあるプロバイダーの状態が悪いときのフォールバックが必要になります。それぞれのケースで直接接続するとなると、それぞれの認証情報、リクエスト形式、エラーセマンティクスを維持することになり、これらの作業は生成したいビデオとは何の関係もありません。

hiapi は Grok テキスト・トゥ・ビデオモデルに統一されたインターフェースを提供します。保持する認証情報は1つ、リクエストの取り決めも1セットだけでよく、grok-imagine/text-to-video と grok-imagine-1.5-lite は同じエンドポイント群の下にあります。バリアントの切り替えはモデル名を変更するだけで、統合を書き直す必要はなく、プロンプトテンプレート、リトライロジック、リソース処理はそのまま維持されます。

さらに運用面の理由もあります。集約アクセスとは、モデルの可用性と非推奨化が上流で処理されることを意味するため、新しい grok-imagine バリアントは再デプロイなしでパイプラインに入ります。ビデオ機能を製品に届けるチームにとって、これはあなたの責任範囲を減らします。プロバイダーの基盤パイプラインを気にする必要はなく、プロンプトと製品体験に責任を持てばよいのです。

モデルバリアントを知る：grok-imagine/text-to-video と grok-imagine-1.5-lite

hiapi は2つの Grok テキスト・トゥ・ビデオバリアントを提供しており、それぞれが忠実度とスループットのトレードオフ曲線上の異なる位置にあります。

grok-imagine/text-to-video

これは汎用テキスト・トゥ・ビデオモデルです。出力品質を優先する場合に選択します。キービジュアルのクリップ、マーケティング素材、コンセプト提案、そして動きが注意深く吟味されるあらゆるケースです。あるプロンプトがどう振る舞うかまだわからない場合には、より安全なデフォルトの選択です。なぜなら、モデルが最も強い状態で評価していることになるからです。

grok-imagine-1.5-lite

lite バリアントは低遅延とリソース消費の削減に取り組みます。反復ループ——プロンプト探索、ストーリーボードのプレビュー、候補クリップの一括生成——に使用します。これらの場面では、まずプロンプトを収束させてから、高コストの生成を行うことを望みます。本番環境では、迅速な応答が完璧な映像よりも重要な、高並列・低リスクの場面にも役立ちます。

どう選ぶか

実用的なルール：草稿には grok-imagine-1.5-lite、最終稿には grok-imagine/text-to-video を使います。両者は hiapi 上で同じリクエストの取り決めを共有するため、クライアント側でモデル名をパラメータ化し、タスク階層に応じて切り替えられます。lite で生成した草稿がすでによさそうなら、同じプロンプトをフルモデルに昇格させて成果物を出力します。そうでなければ、遅く高コストな試行を1回節約できたことになります。

テキスト・トゥ・ビデオリクエストの構成

hiapi 経由で送るすべてのテキスト・トゥ・ビデオ呼び出しは、いくつかの小さな部分で構成されています。それぞれを理解しておくとデバッグがずっと速くなります。

model フィールド

モデル識別子はバリアント（grok-imagine/text-to-video または grok-imagine-1.5-lite）を選択します。関数内に埋め込んだハードコード文字列としてではなく、設定として扱ってください。後で階層ごとのルーティングが必要になるからです。

プロンプト

プロンプトは主要なクリエイティブ入力です。主体、動作、場面、スタイルを重要度の順に記述します。動作のない場面は単なる画像であり、動作を表す節がそれをビデオにする鍵です。プロンプトの構造については後ほど詳しく説明します。

モーションモード

モーションモードは、モデルがカメラと主体の動きをどう解釈するかを導きます。最も見落とされやすいパラメータであり、プロンプトはよいのに出力が「どこか違う」と感じられる最も一般的な原因でもあります。デフォルトのままにせず、プロンプトが記述している内容に合わせてください。

出力と配信

ビデオ生成は非同期です。呼び出しはタスクを返し、そのタスクを完了まで追跡してから、その参照を通じて生成リソースを取得します。レンダリングには実時間がかかるため、クライアントは待機期間を明示的に処理する必要があります。ポーリングや webhook 形式の完了チェックであり、インライン応答を前提にしてはいけません。課金は出力秒数に基づくため、最初の草稿から再生時間の意図に注意してください。

プロンプトに合うモーションモードの選択

モーションモードは強い事前分布です。モデルがプロンプトのより細かなディテールを解析する前に、どの動きに傾くべきかを伝えます。モードとプロンプトが不一致だと、出力は妥協して処理され、どちらも満たさない結果になりがちです。

モードを支配的な動きに合わせる

プロンプトがカメラの動きを記述している場合——ゆっくりとしたプッシュイン、横方向のトラッキングショット、主体の周囲を回る動き——カメラの動き指向のモーションモードを選択します。プロンプトがほぼ静止した画面内で主体が動くことを記述している場合——人が歩く、煙が立ち上る、水が流れる——主体の動き指向のモードを選択します。クリップが固定カメラのショットのように感じられるが微妙な生命感を持つべき場合は、最も抑制されたオプションを選択します。

1つのクリップにつき支配的な動きは1つだけ

数秒のうちにカメラの動き、主体の動作、場面の遷移を同時にこなそうとするクリップは、たいてい混乱して見えます。最も重要な単一の動きを選び、それを支えるモードを設定し、プロンプトには補助的なディテールを記述させ、競合する動詞を加えないようにします。複合的なシーケンスが必要なら、個別のクリップを生成してから編集でつなぎ合わせます。

まずモードを反復し、それからプロンプトを書き直す

結果が違うと感じるが主体やスタイルは正しい場合、まずモーションモードを変更します。長いプロンプトを書き直すよりも実験コストが低く、問題が動きの解釈にあるのか内容の記述にあるのかを切り分けられます。

実際に動くリクエストを段階的に分解する

以下の流れは hiapi 上の Grok テキスト・トゥ・ビデオタスクの一般的な形式です。ペイロード内のパラメータ名はエンドポイントのリクエストスキーマに従います。公開前に、正確なフィールド集合については API リファレンスを確認してください。

ステップ 1：ペイロードを構築する

緩い文字列連結ではなく、構造化されたオブジェクトから始めます。そうすればログに記録して再利用できます。

{
  "model": "grok-imagine/text-to-video",
  "prompt": "夕暮れ時、赤い凧が風に煽られて浜辺で上がり、カメラがゆっくりと上にチルトし、柔らかな金色の光",
  "motion_mode": "<カメラの上チルトに合うモード>"
}

ステップ 2：タスクを送信する

ペイロードをテキスト・トゥ・ビデオエンドポイントに送信し、認証ヘッダーに hiapi の認証情報を含めます。応答はタスク識別子とステータスを返します。その識別子を直ちに永続化してください。それが以降のすべての操作のハンドルになります。

curl -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

ステップ 3：完了をポーリングする

レンダリングは非同期です。バックオフを伴う間隔でタスクのステータスを問い合わせ、タスクが終端状態を報告したら停止します。「pending」と「processing」はエラーではなく正常状態として扱います。

ステップ 4：リソースを取得する

タスク完了後、応答には生成されたビデオへの参照が含まれます。一時的な URL にホットリンクするのではなく、自身のストレージにダウンロードしてください。そうすれば製品が生成物のライフサイクルに依存しなくなります。

ステップ 5：入力を記録する

モデル、プロンプト、モーションモード、タスク id を、保存したリソースと一緒に記録します。クリップが後でよい・悪いと判断されたとき、再現または修正するには正確な入力が必要です。

ビデオモデルが実際に実行できるプロンプトを書く

ビデオプロンプトはムードボードではなくショットの記述です。モデルには、時間軸上でアニメーション化するための具体的で物理的に妥当な指示が必要です。

安定した節の順序を使う

主体、動作、場面、カメラ、スタイル。この順序は重要な内容を前に置き、モデルがディテールと一貫性のどちらかを取捨選択しなければならないときに明確な階層を与えます。テンプレート内で同じ順序を保ち、結果を意味のある形で比較できるようにします。

動作は1つ、動詞で表現する

「自転車に乗る人」は静止画です。「自転車に乗る人が坂をペダルを踏んで上る」ならクリップになります。動作を明示し、単一に保ちます。二次的な動きが欲しい場合は、「坂をペダルを踏んで上り、サイクルジャージがなびく」のように補助的なディテールとして加え、競合する2つ目の動作にはしないでください。

カメラの動きは平易な言葉で記述する

カメラが何をするかを述べます。上にチルト、左にパン、安定を保つ。何を意味するかわからない「ダイナミックアングル」のような曖昧な表現は避けます。カメラの指示が明確であるほど、選択したモーションモードとの連携がよくなります。

スタイルを制約し、仕様は制約しない

光、色調、質感を記述します（「柔らかな金色の光、落ち着いた色彩、わずかな粒子感」）。モデルが公開していない技術的パラメータを発明しないでください。解像度と再生時間はリクエスト設定であり、プロンプトの内容ではありません。両者を混ぜるとモデルとログを読む開発者を混乱させます。

テンプレートライブラリを維持する

ユースケースごとにいくつかのプロンプト骨格——製品ショット、風景、キャラクターの瞬間——を維持し、主体と動作のためのスロットを残します。テンプレートは出力をより一貫させ、失敗を単一の変更された変数に帰属させやすくします。

本番環境のために統合を堅牢化する

最初の成功呼び出しは簡単な部分です。デモと製品を分けるのは、タスクが遅いとき、プロンプトが拒否されたとき、トラフィックが急増したときに統合がどう振る舞うかです。

生成をキューとして扱う

ビデオのレンダリングを待ってユーザーリクエストをブロックしないでください。タスクを送信し、タスク id をクライアントに返し、ワーカーに完了をポーリングさせ、準備ができたら結果をプッシュさせます。これによりリクエストの遅延をレンダリングの遅延から切り離し、ユーザーに再プロンプトを求めずにリトライできます。

バックオフ付きでリトライし、リトライ可能な失敗のみリトライする

一時的なエラーとタイムアウトは、ジッター付きの指数バックオフに値します。検証エラー——形式の誤ったプロンプトやサポートされていないフィールド——は毎回同じように失敗します。それらはリトライを無駄にせず、呼び出し元に提示します。クライアントコードでエラーを明示的に分類します。

モデルを階層化する

草稿を grok-imagine-1.5-lite にルーティングし、最終稿を grok-imagine/text-to-video にルーティングします。課金は出力秒数に基づくため、草稿層こそ支出を制御する場所です。低コストでプロンプトを収束させ、それから昇格させます。ユーザーごとの並列タスク数を制限し、暴走する生成ループを防ぎます。

プロンプトをバージョン管理する

プロンプトをバージョンタグ付きで保存し、どのバージョンがどのリソースを生成したかを記録します。テンプレートを変更したとき、以前の出力と比較し、推測に頼らずに回帰をロールバックできます。

リソースを検証し、できなければ破棄する

ユーザーに表示する前に、取得したビデオに軽量なチェック——ファイルの完全性、想定される再生時間、内容が空でないこと——を実行します。低コストの検証ステップは、壊れたプレーヤーが顧客の前に現れるのを防ぎ、あるモデルバリアントが異常な振る舞いをしていることを教えてくれます。

1つのエンドポイント、2つのモデル階層、慎重に選ばれたモーションモードがあれば、Grok テキスト・トゥ・ビデオ API は本番パイプラインにきれいに組み込めます。まず grok-imagine/text-to-video 上の単一のプロンプトから始め、ループをエンドツーエンドで動かし、それから反復のために lite 階層を追加してください。