使用ガイド
HiAPI API で veo-3.1-lite/text-to-video を使ってショート動画を構築する
実践的な開発者ワークフロー:絵コンテに基づくテキストto動画、ネイティブ音声、アスペクト比の選択
このページの内容
なぜショート動画では素朴なテキストto動画プロンプトが機能しないのか
テキストto動画モデルを初めて触ると、長く映画的なプロンプトを書いて、完成した動画が返ってくることを期待しがちです。30 秒のショート動画作品では、このやり方はほぼ常に期待を裏切ります。その理由はプロンプトの練り込み具合ではなく、構造にあります。
単一のプロンプトは、モデルに対してストーリー全体にわたる連続性を要求します。キャラクターの一貫性、カメラワーク、テンポ、音声のすべてが、尺全体を通して一貫していなければなりません。しかしショート動画は 1 本の長回しではなく、一連のビートの連なりです。フック、セットアップ、転換、締め。各ビートには異なる構図、異なるエネルギー、そして多くの場合、異なる被写体の配置が必要です。それらを 1 本のプロンプトに詰め込むと、モデルはそれらを平均化してしまい、その平均化こそがショート動画のリテンションを破壊します。
もう 1 つの失敗パターンはイテレーションのコストです。1 本のプロンプトが長い動画を生成し、3 番目のビートがうまくいかなかったとき、あなたは全体を再生成して、気に入った部分が残ることを祈るしかありません。これは遅いループであり、確実な制御手段がありません。
本ガイドで採用するワークフローはショット単位です。スクリプトを個別のショットに分解し、ショットごとに個別の生成リクエストを送り、連続性はプロンプトの中ではなく、自分のメタデータの中で管理します。以降の各セクションはこの分解の上に積み重なります。リクエスト構造、アスペクト比、音声、イテレーションはすべて、ショット単位で作業することを前提としています。
ここが veo-3.1-lite/text-to-video が自然に適合する点です。より軽量なテキストto動画モデルは、短く個別に再生成できるクリップを多数生成するのに非常に適しており、それはまさにショート動画パイプラインの形です。
メンタルモデルの転換
モデルを、完成品を返してくれる監督として扱うのはやめましょう。モデルをショットレンダラーとして扱います。あなたは範囲を明確に定めたショット記述を渡し、モデルはクリップを返し、並べ替え、音声ミックス、テンポはあなたのパイプラインが担います。この役割分担が明確になれば、残りの意思決定のほとんどはプロンプト執筆ではなくエンジニアリングの意思決定になります。
API を呼び出す前にショットリストを計画する
ショットリストはスクリプトと生成呼び出しの間の契約です。散文ではなくデータとして書くことで、パイプラインがそれを走査できるようになります。
スクリプトから始めて、ビートに分割します。ショート動画では、実用的なルールとして「1 文につき 1 ショット、または 1 つの視覚的アイデアにつき 1 ショット」とし、短い方を採用します。1 つの文を表現するのに 2 つのカメラアングルが必要なら、それは 2 ショットです。3 つの文が 1 つの連続した視覚を共有しているなら、それらは 1 ショットにできます。ただし、尺が 1 回の生成に余裕をもって収まる場合に限ります。
各ショットについて、少なくとも次を記録します。
- ショット ID——安定していて人間が読める識別子。キャッシュとリトライに使います。
- プロンプト——視覚的な記述。そのショットが単独で成立するのに十分な自己完結性を持たせます。
- 尺——最終編集でそのショットが続くべき長さ。
- アスペクト比——チャネルごとに決定し、生成前に決めます。
- 音声の意図——ネイティブな環境音、置き換えるための無音、またはナレーション用のプレースホルダー。
- 連続性のメモ——キャラクターの衣装、照明、場所、スクリーン上の向き。
可能な限り連続性をプロンプトの外に出す
連続性のメモは、プロンプトごとに逐語的に繰り返すのではなく、メタデータに置くべきです。長い再利用記述を抱えたプロンプトは、強調の重点がずれやすいものです。あるショットでは衣装を過度に強調し、次のショットでは不足する、といった具合です。よりクリーンなパターンは、キャラクターや場所ごとに短く安定した記述ブロックを用意し、あなた(パイプラインの作者)がそれを各プロンプトに組み立てる方法です。そうすれば、プロンプト自体が異なっていても、文言がショット間で完全に一致します。
1 ショットを 1 リクエストに対応させる
各ショットは 1 回の呼び出しで生成できるべきです。1 回の生成で余裕をもってカバーできる範囲を超える尺が必要なショットは、リクエストを引き伸ばすのではなく、自然なカットポイント(リアクション、カメラの動き、一拍の沈黙など)で分割します。短いショットは、1 つが失敗したときの再生成コストも低く、それこそが分解の意義です。
ショットリストはスクリプトと一緒にバージョン管理に置きます。スクリプトが変わったとき、差分がどのショットを再レンダリングすべきかを正確に教えてくれます。
パイプライン内で生成リクエストを構築する
ショットリストがデータとして手に入れば、リクエスト層は薄いラッパーになります。1 つのショットを読み取り、veo-3.1-lite/text-to-video 向けのリクエストを構築し、HiAPI API を呼び出し、ショット ID をキーに結果を保存します。
大まかに言えば、1 回の生成呼び出しが運ぶ情報はショット記録と同じです。プロンプトテキスト、想定尺、アスペクト比です。正確なパラメータ名と許容値は、HiAPI 上のモデルの API リファレンスで定義されているため、エンドポイントのドキュメントを唯一の情報源とし、ラッパー層のデフォルト値をそれに合わせます。多数の場所で前提をハードコードしないようにします。
再利用可能なラッパー
以下の形は意図的に言語非依存の擬似コードにしています。価値は構文ではなく構造にあります。
function renderShot(shot, attempt):
request = {
model: "veo-3.1-lite/text-to-video",
prompt: buildPrompt(shot),
duration: shot.duration,
aspect_ratio: shot.aspectRatio
}
response = hiapi.generate(request)
save(shot.id, attempt, response)
return response
このラッパーを用意する価値があるのは、次の 3 つの特性です。
- すべての呼び出しがショット ID と試行回数をキーにする。4 番目のショットが失敗したとき、どの成果物を置き換えるべきか、どの試行が失敗したかを正確に把握できます。
- プロンプトは組み立てられるもので、貼り付けるものではない。
buildPromptはショット自身の記述と、メタデータ内の安定したキャラクター・場所の記述ブロックを結合し、連続性の文言をショット間で一貫させます。 - 下流は最初の呼び出しの成功に依存しない。ラッパーは成果物への参照を返し、結合処理は各ショットの現在承認済みの内容を読み取ります。
実際には生成は非同期である
生成はリクエストハンドラ内で同期的に呼ぶ処理ではなく、長時間実行タスクとして扱います。ジョブを送信し、ジョブ参照を永続化し、ワーカープロセスでポーリングまたは完了待ちをします。そうすれば、リトライ、同時実行数制限、部分的な失敗は、アプリケーションのリクエストライフサイクルに絡みつくことなく、あなたの制御下に置かれます。
結合は独立したフェーズ
1 つのステップで生成と結合を行わないでください。承認済みのすべてのショットをレンダリングして保存し、その後に別のアセンブリ処理を実行します。ショット ID 順に並べ、連結し、トランジション(あれば)を適用し、音声をミックスします。アセンブリを独立させることで、1 つのショットを再レンダリングするときはアセンブリを再実行するだけで済み、何も再生成する必要がありません。
チャネルごとにアスペクト比とクリップの長さを選ぶ
アスペクト比と尺は、生成が始まる前に、配信チャネルから逆算して決めるべきです。後から調整するものではありません。完成したクリップを別の画枠にクロップするのは、レンダリングを無駄にする最も一般的な方法です。
アスペクト比
チャネルごとに主画枠を 1 つ選び、作品全体でそれを維持します。1 本のショート動画内でアスペクト比を混在させると、どのプラットフォームでも視聴体験が壊れます。
- 縦向き——フィードをスワイプするショート動画 UI のデフォルト。縦長画枠向けに構図を組みます。被写体は中央またはやや上に置き、上下に UI オーバーレイ用のセーフマージンを確保します。
- 横向き——埋め込みプレーヤー、Web サイトのヒーロー動画、視聴者が静止しているプレゼン用途に。
- 正方形——グリッドレイアウトで時折使われます。逃げではなく、意図的な選択として扱います。
ショットリストへの実際の影響としては、縦向きの構図は画面内に収められる内容を変えます。横向きでうまく機能するワイドな確立ショットは、縦長画枠に圧縮されると判別しにくくなるかもしれません。まず比率を決め、それからその構図向けにショットを書きます。
クリップの長さ
クリップの長さは、モデルが最大でどれだけ生成できるかではなく、テンポによって決まります。いくつかの指針を示します。
- フックは短く。最初のショットはたいてい注意をつかむか失うかを決めます。コンパクトに、かつ視覚的に明確に保ちます。
- 1 クリップに 1 つのアイデア。1 つのショットに 2 つの異なる視覚的出来事が含まれるなら、分割します。短いクリップは、編集時に最終テンポをより細かく制御できるようにもします。
- トリミングの余白を残す。目標のカットポイントより少し長めに生成し、アセンブリ時に切り落とします。トリミングは無料ですが、再生成は無料ではありません。
- プラットフォームの集計と照合する。総尺は各ショットの合計です。生成前に計画尺を合計し、そのシーケンスがそのチャネルの典型的な消費時間に合うか確認します。ショットリストを再調整する方が、再レンダリングするよりずっと簡単です。
比率ごとに 1 回だけ生成する
同じ作品を 2 つの画枠で本当に必要とするなら、それらを 2 つの独立した納品物として扱い、それぞれに 2 つのショットリストを用意します。プロンプトを共有するのは問題ありませんが、レンダリングを共有するのは構図が異なるため問題ありません。アスペクト比をショットのメタデータにエンコードすることでこれが明確になり、意図しないチャネル間の再利用を防げます。
ネイティブ音声とナレーションを組み合わせる
veo-3.1-lite/text-to-video は映像と一緒にネイティブ音声を生成でき、その音声は実際に役立ちます。環境音、環境の質感、単純なダイジェティックな効果音は、無音にはない存在感をクリップに与えます。誤りは、ネイティブ音声と自分のナレーションの両方に同じ役割を担わせようとすることです。
効果的な役割分担は、ネイティブ音声が世界を担い、ナレーションが情報を担うことです。ネイティブ音声トラックにすでに音声のような内容や強い音楽の土台が含まれていると、ミックス時に衝突します。ショットごとにどちらのトラックが主導するかを決めます。
ミックスの順序
- まずナレーションを敷く。ナレーションのタイミングはスクリプトで固定されています。他のすべてはそれに合わせます。
- ネイティブ音声を下層に置く。ネイティブトラックが環境音や質感である場合、聞こえる状態にしつつ従属させます。
- 削除するのではなく、下げる。ナレーションの下でネイティブトラックを完全に切るのではなく音量を下げます。セリフの間に突然の無音があると不自然に聞こえます。各ショット境界でゲインを滑らかに遷移させます。
- 最後に正規化する。ショットごとにミックスしてから連結すると、音量レベルに段差が生じます。結合後の作品に対して最終処理を 1 回実行します。
ネイティブ音声トラックを無音にする場合
次の場合には無音にするか、より明確な音声の意図でそのショットを再生成します。
- ネイティブ音声に理解可能な音声が含まれ、ナレーションと競合している。
- 質感がシーンに合っていない(例:屋外ショットに屋内の環境音が入っている)。
- 作品全体を 1 本の連続した音楽の土台で演出していて、ネイティブトラック自体のリズムがそれと衝突する。
これらは通常ショット単位で検出でき、それもショットを独立させるもう 1 つの理由です。他の部分に触れずに、1 つのショットの音声だけを再生成できます。
音声の意図をショットリストに書き込む
各ショットに明示的な音声フィールドを追加します。native_ambience、silent、voiceover_covered のいずれかです。これにより生成前に決定を迫られ、アセンブリ段階に対してどのショットを音量を下げるべきか、どれはネイティブトラックを単に破棄すればよいかを伝えられます。
複数回の試行を通じて品質とコストを管理する
イテレーションの規律は、収束するパイプラインとレンダリングを無駄に消費するパイプラインを分ける鍵です。良いニュースは、ショット単位の生成が正しい習慣を自然なものにすることです。
単一のショットだけを再生成し、シーケンス全体は絶対に再生成しない
あるビートが失敗したら、そのショットを置き換えます。ラッパーは結果をショット ID と試行回数でキーにしているので、修正は 1 つの ID に対して新しい試行を発行し、アセンブリを再実行するだけです。1 つのショットを直すために複数のショットを再レンダリングしていることに気づいたら、ショットリストが粗すぎる可能性があります。さらに分割しましょう。
承認済みのクリップを積極的にキャッシュする
1 つのショットが承認されたら、それを不変として扱い、ショット ID とそのプロンプトおよびパラメータのハッシュをキーにして永続保存します。パイプラインを再実行すると、変更のないものはすべてスキップされます。これは、映像を固定したままミックスを反復する音声とテンポの作業中に最も重要です。
各試行では 1 つの変数だけを変える
あるショットが期待に達しないとき、1 つのこと(プロンプトの具体性、尺、構図)を調整してから再生成します。3 つの変数を同時に変えると、どの修正が効いたのかわからず、次のショットで同じ教訓を学び直すことになります。
試行を拡大する前にレシピを固める
1 つのシーケンス全体を満足のいく状態にしてから、それをバリエーションのテンプレートとして使います。別のフック、異なる CTA などです。ショットリストはデータなので、バリエーションは新しいプロジェクトではなく小さな差分にすぎません。
完成分ではなくショット数で予算を組む
作業単位はショットなので、イテレーションの単位もショットです。バッチを生成する前に、ショット数とショットあたりの想定試行回数を計算します。この数字とモデルの課金基準を組み合わせたものが計画の数字になります。古い前提を引き継ぐのではなく、HiAPI の料金パネルで現在のレートを確認してください。
最終サイズでレビューする
各ショットを実際のアスペクト比で、視聴者が見る画面で確認します。デスクトップの横向きサイズでは見えない問題が、縦向きのフィードでは明らかになります。レビュー時に見つける方が、公開後に見つけるよりずっと安く済みます。
よくある生成問題をトラブルシュートする
あるショットが使えない状態で返ってきたら、次のチェックを順に実行します。これらは失敗の大部分をカバーし、最初の 2 項目でほとんどの問題が解決します。
1. プロンプトの具体性
プロンプトは自己完結しているでしょうか。被写体、動作、構図、照明を記述しているでしょうか、それとも隣接ショットのコンテキストに依存しているでしょうか。ショットのプロンプトは単独で成立しなければなりません。モデルはあなたが送った内容しか見ていません。曖昧な被写体記述はドリフトを招き、過密なプロンプトはごちゃつきを招きます。目標は、ショットごとに 1 つの明確な被写体と 1 つの明確な動作です。
2. ショットの長さ
その尺のショットに対してあまりに多くのことをしていないでしょうか。1 つのプロンプトが短いクリップの中で複数の視覚的出来事を示唆していると、モデルはそれらを圧縮します。ショットを分割するか、長くします。逆に、尺に対して内容が少なすぎるショットは目的なく漂いがちです。切り詰めましょう。
3. アスペクト比の不一致
実際にリクエストしている画枠向けにプロンプトを書いているでしょうか。縦長画枠にワイドで横長の記述を書くと、不自然なクロップとデッドスペースが生まれます。ショットの視覚記述がそのアスペクト比と一致しているか、またパイプラインの他の段階がこっそり再クロップしていないかを確認します。
4. 音声の衝突
映像は問題ないのに結果がしっくりこない場合、ネイティブ音声トラックを単独で聞いてみます。競合する音声、誤った環境音、ナレーション下の強いリズムは、たいてい視覚ではなく音声の問題です。ネイティブトラックを無音にするか、ショットの音声の意図を調整して修正し、再ミックスします。映像を再生成する必要はありません。
5. パイプラインとパラメータのエラー
生成が直接失敗するか、リクエストと一致しない内容が返ってくる場合、HiAPI 上のエンドポイントドキュメントに対してパラメータを検証します。モデル識別子のスペルが正しいか、尺とアスペクト比の値が許容範囲内か、プロンプトが空でないか。これらのエラーは退屈ですが、複数の場所でデフォルト値をハードコードするラッパーではよく起こります。それこそがリクエスト構築を 1 つの関数に保つ理由です。
6. ショット間の連続性のドリフト
各ショットは問題なく見えるのにシーケンスが一貫しない場合、問題は生成ではなくメタデータにあります。各ショットの組み立て後のプロンプトテキストを比較します。キャラクターや場所の記述子の文言が異なっているなら、共有記述ブロックでそれらを揃え、ずれているショットだけを再生成します。
リストを順に処理し、どのチェックが各失敗を解決したかを記録します。いくつかのシーケンスを経れば、どのチェックがあなたのコンテンツで支配的かがわかり、トラブルシュートは再構築ではなく素早いスキャンになります。HiAPI API を通じて veo-3.1-lite/text-to-video でショットのレンダリングを始め、数字は料金パネルに任せて、あなたはシーケンスに集中できます。