Runway API テキストtoビデオ：hiapi経由でGen-4.5を呼び出す開発者ガイド

なぜマネージド型テキストtoビデオエンドポイントを使うのか

テキストtoビデオは画像生成や編集ワークフローの代替品ではない——それは異なる基礎能力である。画像モデルは静止画を返し、あなたはそれをトリミング、レタッチ、合成できる。テキストtoビデオの呼び出しが返すのは動きだ：カメラワーク、被写体の動作、そして時間とともに変化する光。あなたの製品がある映像クリップを必要としているなら——短いマーケティング映像、アプリ内の背景ループ、シーンのプレビュー——単発の「リクエストからクリップへ」の呼び出しは、アイデアから素材への最短経路であることが多い。

その代償はコントロールだ。キーフレームで動きを設定するのではなく、言葉で動きを記述するため、モデルが自ら解釈する必要がある。そのためプロンプトの品質は画像タスク以上に重要になり、反復ループも一発勝負以上に重要になる。

hiapi経由で提供されるマネージドエンドポイントは、この基礎能力を支えるインフラ作業を取り除く：一貫したインターフェース、統一された認証情報モデル、そして呼び出す動画モデル間で統一されたレスポンス構造が得られる。時間はストレージパイプラインやジョブポーリング、各社SDKではなく、プロンプトと製品への統合に費やせる。

適する場面：

• ユーザー入力やテンプレートに基づいてオンデマンド生成される短いクリップ
• 本格的な制作パイプラインに投資する前の迅速なコンセプト探索
• 生成に多少の瑕疵があっても使える背景やB-roll素材

適さない場面：フレーム単位で正確な連続性、決定論的な出力、長尺の物語的一貫性が必要なあらゆる要件。利用可能な結果ごとに、複数の候補クリップ分の予算を確保しておこう。

runway-gen-4.5/text-to-videoエンドポイントの構造

概念的には、runway-gen-4.5/text-to-videoへのリクエストは3つの部分で構成される：プロンプト、リクエスト単位の設定、そしてあなたのID／認可だ。創造的なのは最初の部分だけで、残り2つはモデルの動作方法と課金方法を決める。

送信するもの

• プロンプト文字列。主要な創造的入力——被写体、動作、カメラ、光、雰囲気を自然言語で記述する。
• リクエスト単位の設定。アスペクト比、長さ、そしてエンドポイントが公開する生成フラグ。これらは出力のコンテナ形状を決めるのであって、内容を決めるのではない。
• 認証ヘッダー。hiapiのキーで、毎回の呼び出しに付与する。機密として扱い、クライアントコードに含めて公開してはならない。

受け取るもの

動画生成は瞬時には完了しないため、エンドポイントの呼び出し方によって、ポーリングが必要なジョブハンドルを受け取るか、メディアURLに解決されるレスポンスを受け取る。いずれの場合も、受け取るのは生成されたクリップへの参照であり、インラインの生バイトではない。返されたURLの有効期限後も素材を使い続ける必要がある場合は、ダウンロードして自身のストレージに永続化せよ。

有用なメンタルモデル：このエンドポイントは(prompt, settings)をクリップとメタデータにマッピングする関数だ。統合側はこれを非同期で、リトライ可能で、非決定論的であるものとして扱うべきだ——同じ入力が常に同じクリップを生むとは限らず、それは想定内の挙動であって欠陥ではない。

リクエスト構築は単純で退屈なものに保て。リクエストボディを組み立て、認証を付与し、呼び出しを送信し、レスポンスを{ status, videoUrl, error }に正規化する小さな内部ラッパーを1つ書け。本ガイドの以降のすべてのセクションは、このラッパーがすでに存在することを前提とする。

動きの中でも成立する映画的なプロンプトを書く

曖昧な形容詞は動きの中で崩れる。「A beautiful cinematic shot of a city」はモデルにアニメーションできるものを何も与えず、結果として漠然と漂うような映像が生成される。解決策は、撮影監督が必要とする4つの要素を明確にすることだ：被写体、カメラ、光、動き。

被写体と動作を名指しする

画面に何があり、それがクリップ全体を通じて何をするのかを述べよ。始点と暗黙の終点を与え、モデルにたどるべき運動の軌跡を持たせよ。

A lone cyclist rides from left to right along a wet coastal road, 
pedaling steadily as spray kicks up from the rear wheel.

カメラを明示的に指定する

モデルが動きにマッピングできるカメラ言語を使え：ゆっくりとしたプッシュイン、固定のワイドショット、ハンドヘルドのフォロー、ローアングルのトラッキング、ゆっくりとした右パン、空撮の下降。クリップごとにカメラの動きは1つだけにしたほうが、3つの相反する動きよりも安全だ。

Static wide shot, camera at ground level, no zoom.

光と時間を指定する

光は知覚される制作品質の大部分を決める。光源と質感を与えよ：曇天の拡散日光、レンズ左側からの強い午後の日差し、夜の濡れた反射に映る実景のネオン。

物理的に信憑性のある動きを描写する

短いクリップの中での速い動きはぶれる。多くの速い出来事よりも、中程度の速度の読み取れる単一の動作を選べ。緊張感が欲しいなら、十数の出来事を同時に起こすのではなく、カメラワークと光から得よ。

1段落に保つ

1〜3文の簡潔な段落は、箇条書きの仕様リストに勝る。願望リストではなく、ショットの記述として書け。スタイル形容詞の重ね掛けは避け、1つのルックを選んで貫け。

信頼できるテンプレート：

[Subject + action]. [Camera framing and movement]. [Lighting and time of day]. [Environment and atmosphere].

設定を何か変更する前に、まずプロンプトをこのテンプレートに書き直せ。

実行可能なリクエスト、ステップごとの説明

このウォークスルーはNode.jsとラッパー関数を前提とするが、構造は特定の言語に依存しない。

ステップ1：ショットを書く

A chef slices vegetables on a wooden board in a small kitchen, 
hands moving steadily. Static medium close-up, camera at counter height, 
no zoom. Warm tungsten light from an overhead lamp, soft shadows, 
light steam in the background.

ステップ2：リクエスト設定を選ぶ

クリップの最終的な使用場所に合ったアスペクト比と、物語を語るのに十分な最短の長さを選べ。短いクリップは早く失敗し、探索コストも低い。

ステップ3：呼び出しを送信する

const res = await fetch(`${HIAPI_BASE}/runway-gen-4.5/text-to-video`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.HIAPI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: shotPrompt,
    aspect_ratio: '16:9',
    duration: 5,
  }),
});

const data = await res.json();
if (!res.ok) throw new Error(data.error ?? `HTTP ${res.status}`);

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

レスポンスがジョブハンドルを持っている場合は、小さめのバックオフ間隔で終状態に達するまでポーリングせよ。メディアURLを直接持っている場合はステップ5に進め。

ステップ5：素材を永続化する

クリップをダウンロードし、自身のキーで保存せよ。返されたURLは一時的なアドレスとして扱え。

ステップ6：意思決定ポイントを記録する

プロンプト、設定、生成された素材をまとめて記録せよ。このログこそが、次のセクション——チューニング——を当て推量ではなく実行可能なものにする。

プロンプトを変更せずに出力をチューニングする

クリップが期待外れのとき、反射的にプロンプトを書き直したくなる。まずは1回こらえよ。プロンプトと設定は独立した変数であり、両方を同時に変えると、どちらが本当の原因だったかを判断する能力が損なわれる。

変数を分離する

プロンプトを固定し、リクエスト単位の設定をちょうど1つだけ変えよ——アスペクト比、長さ、またはある生成フラグ。再実行せよ。クリップが改善したなら、問題は創造的側面ではなく構造的側面にあったということだ。改善しなければ、その設定を元に戻し、プロンプトの変更に移れ。

構造的な問題は設定で解決する

• 構図が配置先と合わない？アスペクト比を変えよ。
• 動作が完了する前に切れている？長さを増やせ。
• すべてが定まらず漂い、アンカーがない？クリップを短くし、漂う時間を減らせ。

内容の問題はプロンプトの修正で解決する

• 被写体が違う、または欠けている？もっと早く名指しし、具体的にせよ。
• カメラが揺れ動く？望む1つの動き以外のカメラ用語をすべて削除せよ。
• 平坦で生気がない？光源と方向を加えよ。

小さなA/Bテストを行う

1つのシードプロンプトを固定し、それぞれ1つの節だけを変えた3つのバリエーションを生成せよ。記憶ではなく、並べて比較せよ。非決定論的であるということは、1つの悪いクリップは証拠にならないということだ。ある節が有害だと断定する前に、2〜3回の実行でパターンを探せ。

すでに維持しているログに結論を書き留めよ。十数回の反復を経て、これはあなたの製品固有のプロンプトと設定の手引きとなり、その価値はどんな汎用プロンプト集よりも大きい。

よくある失敗のデバッグ

最初の1週間の失敗のほとんどは4つのカテゴリに分類できる。それぞれ調査の道筋が異なる。

リクエストが拒否またはブロックされた

ポリシー情報を伴う非2xxレスポンスは、プロンプトまたは設定が受け入れられなかったことを意味する。盲目的にリトライするのではなく、エラーレスポンスボディを読め。問題のある記述を書き直し、実名の実在人物やブランドを削除してから再送信せよ。拒否されたプロンプトはそのまま記録せよ——繰り返し発生する拒否は、多くの場合プロンプトテンプレート内の習慣に遡ることができる。

タイムアウト

動画生成は遅い。HTTPクライアントがエンドポイントの応答前にタイムアウトしても、ジョブは実行中で課金されている可能性がある。生成系呼び出しのためにクライアントのタイムアウトを延ばし、ポーリングはリクエストをぶら下げたままにするのではなくバックグラウンドワーカーに移せ。

空のクリップまたは使用不能なクリップ

レスポンスは成功しているのにクリップに判別可能な被写体がない場合、通常はプロンプトが抽象的すぎることを意味する。被写体・カメラ・光・動きのテンプレートに照らして読み直せ。4つのうち1つでも欠けていれば、それが修正すべき箇所だ。

認証と設定のエラー

401と403はプロンプトではなくキーの問題を意味する。キーがローカルシェルだけでなく実行環境に存在することを確認し、ヘッダー形式を確認せよ。この種の失敗は早期に発見するほどコストが低く、本番での発見はコストが高い。

一般的なルール：何かを変更する前にエラーを分類せよ。プロンプト系のエラー、設定系のエラー、インフラ系のエラーは異なる修正を必要とし、混同すると生成予算を無駄にする。

コスト、レイテンシ、本番向けの防御策

ローンチ前に、失敗時にエンドポイントがどう振る舞うかを決めておけ。動画生成はほとんどの製品で最も高価で最も遅い呼び出しだからだ。

呼び出し単位ではなくクリップ単位で予算を組む

動画の課金は通常出力の長さに連動するため、長いクリップは短いクリップより高価だ。API呼び出し回数を数えるのではなく、リトライや拒否された候補を含めた完成クリップ単位で予算を組め。ユーザーごと、セッションごとに生成上限を設定せよ。現在の料金は価格パネルを参照し、ビジネスロジックにハードコードしてはならない。

レイテンシを前提に設計する

ユーザー向けリクエストを生成でブロックさせては決してならない。ジョブを開始し、直ちにハンドルを返し、ポーリング、webhook、または通知でクリップを届けよ。UIに進捗を表示し、遅いレンダリングが進行中の作業として読めるようにし、固まっているようには見せない。プロンプトと設定ごとに生成済みクリップをキャッシュし、重複リクエストによる再生成を避けよ。

生成前に検証する

呼び出し前の安価なチェックが、呼び出し後の高価な処理を省く：

• ラッパー内でプロンプトの最小長と最大長を強制する
• 被写体または動作を欠くプロンプトを拒否する
• アスペクト比をレンダリングターゲットに照らして検証する
• ユーザーがクォータ内にいることを確認する

入口と出口の両方でモデレーションを行う

送信前にプロンプトのテキストチェックを行う。表示前に返されたクリップの軽量チェックを行う。どちらも1件のサポートインシデントより安い。

フォールバックを用意する

生成が失敗したり時間がかかりすぎたりした場合、エラーを出すのではなく、静的なカバーフレームやプレースホルダークリップを提供せよ。機能は中断するのではなく、劣化するべきだ。

1つのエンドポイント、1つのラッパー、1つのログから始めよ。製品が実際にどこで失敗するかを学ぶにつれて防御策を徐々に追加し、価格パネルを常にコストの唯一の信頼できる情報源とせよ。