HiAPI API で vidu-q4-preview を使った参照ベース動画生成ショート動画ワークフロー

参照ベース動画生成がショート動画ワークフローを変える理由

プロンプトだけに頼る生成では、モデルが主体の外見、服装、構図、動作、音声のすべてを自ら創造する必要があります。単発の実験ならそれで問題ありません。しかしショート動画制作——同じキャラクターや配信者が何十ものクリップに登場しなければならない——では、プロンプトだけによる制御はすぐに破綻します。文言のわずかな変化が大きな視覚的ドリフトを生み、どれほどプロンプトエンジニアリングを重ねても、顔や衣装、声を確実に固定することはできません。

参照ベース動画生成はこの約束を変えます。テキストで主体を描写する代わりに、モデルに一連の参照素材——アイデンティティを確立する複数の画像と、主体の声を確立する音声リファレンス——を渡し、プロンプトには「誰が」ではなく「何が起こるか」を記述させます。創作制御はトークンレベルの文言から素材レベルのキュレーションへと移り、素材準備が後付けの作業ではなくワークフロー最初のエンジニアリング工程になります。

この転換はショート動画コンテンツの実際の制作方法と完全に整合します：

• 再利用可能なアイデンティティ。審査済みの参照セットは複数のクリップで再利用できるため、シリーズは再プロンプトなしで視覚的一貫性を保てます。
• 関心の分離。脚本家はプロンプト内の動作とテンポを担当し、素材担当者は参照セット内の外見と声を担当します。
• 検証可能な入力。出力がおかしいとき、どの形容詞が結果を変えたかを推測するのではなく、実行間で参照セットを比較できます。

ショート動画は失敗コストの閾値も高めます。クリップの配信は安価ですが再撮影は高価であるため、固定された参照ライブラリから予測可能な変化を生み出すパイプラインは、たまに優れた単発成果を生むパイプラインよりも価値があります。参照ベース動画生成こそが、この予測可能性を可能にする仕組みです。

変わらない部分

プロンプトを書く必要は依然としてあり、非同期スタイルのリクエストを送信し、返された動画を後処理する必要もあります。違いは、参照素材が一級入力となり、プロンプトと同様にバージョン管理、検証、保存を行う必要がある点です。

vidu-q4-preview 参照モデルが HiAPI にどう組み込まれるか

HiAPI 上では、vidu-q4-preview/reference-to-video がモデル識別子として、他の生成タスクで使用するのと同じリクエストインターフェースで指定されます。別途ベンダー SDK を導入する必要も、第二の認証情報を管理する必要もありません。アプリケーションが HiAPI API を呼び出すと、プラットフォームがリクエストを参照ベース動画モデルにルーティングし、レスポンスが生成された動画素材を返します。

このレイヤリングは二つの点で実用的な意味を持ちます：

1. 単一の統合インターフェース。認証、リクエスト構造、エラー処理は使用するモデル間で一貫しているため、モデルの追加や変更は新しいクライアントではなく設定変更になります。
2. 統一された運用ツール。ログ記録、リトライ、レート処理、レスポンス解析が一か所に集中し、参照ベース動画の経路が並行したコードベースになるのを防ぎます。

このエンドポイントの用途

参照ベース動画モデルは、主体のアイデンティティをテキストから創作するのではなく、提供された素材で固定しなければならないクリップ——短いプロモーションクリップ、固定配信者のパート、一貫したモデルが登場する製品ショット、その他シリーズの一貫性が必要なコンテンツ——に適しています。汎用動画エディタではありません。参照とプロンプトに基づいて新しいクリップを生成します。

モデル識別子は設定として扱う

モデル識別子とそのサポートパラメータは、モデルの追加、プレビュー、廃止に伴って変化します。vidu-q4-preview/reference-to-video を十数か所のビジネスロジックにハードコードしないでください。設定レイヤーに保持し、リリース前に HiAPI の公開ドキュメントで現在の識別子、サポートされるパラメータ、想定される入力形状を確認してください。本ガイドのリクエスト構造に関する記述は形状の概要です。正確なフィールド名についてはドキュメントが権威ある情報源です。

本ガイドが扱わない内容

料金は意図的に対象外です。HiAPI の課金は送信したモデルとパラメータに基づきタスク単位で計量され、リアルタイムの数字はチュートリアルではなくプラットフォームの価格パネルに属します。個々のモデルの遅延やスループットに関する主張も同様です——ブログ記事からコピーした数字を信じるのではなく、自分のワークロードで測定してください。

複数画像と音声リファレンスを準備する

参照の品質が出力品質を支配します。素材準備に真剣なエンジニアリング時間を割いてください。モデルの一貫性は、提供した参照の質を超えることはできません。

複数画像リファレンスを選ぶ

同一主体を異なるが互換性のある条件——異なる角度、わずかに異なる照明、クローズアップとミディアムショットの混合——で描いた複数の画像を使用してください。目標は、矛盾を導入せずに複数の視点からアイデンティティを解釈できる十分なカバレッジをモデルに与えることです。

実用的な選択ルール：

• 同一主体、同一時期。モデルに平均化を望まない限り、髪型、ひげ、スタイリングが異なる外見の参照を混在させないでください。
• 一貫したカラー処理。参照間のホワイトバランスやカラーグレーディングの差異が大きすぎると、モデルは不安定なパレットへと誘導されます。
• 競合する主体なし。目立つ顔が二つ含まれる参照セットは混成を引き起こしやすくなります。セットごとに主体は一つです。
• 十分な解像度。縮小や強い圧縮がされた参照は、モデルが必要とする精密なディテールを失います。

音声リファレンスを準備する

音声リファレンスは声色と表現方法を確立します。クリーンな音声を提供してください——低いノイズフロア、BGM なし、話者の重なりなし。意図する表現方法を最もよく代表するセグメントにトリムし、完全な独白ではなく代表的な長さに保ってください。同じ声でシリーズを制作する予定なら、一つの音声リファレンスを固定して再利用してください。

素材を正規化する

あらゆる素材がリクエストビルダーに到達する前に、正規化ステップを通してください。セット内で一貫した画像形式とサイズ、一貫した音声形式とサンプリングレート。正規化は「昨日は動いていた」類の障害を一掃し、キャッシュキーを意味あるものにします。

参照セットをバージョン管理する

参照セットを識別子付きの成果物として扱ってください：

refsets/
  presenter-a/
    v1/  images/  voice.wav  manifest.json
    v2/  images/  voice.wav  manifest.json

マニフェストには素材の出所、適用した正規化、各ファイルのハッシュを記録すべきです。出力がドリフトしたとき、参照セットが変わったかどうかを即座に判断できます。参照セットが変わっていないのにドリフトする場合は、プロンプトやモデルバージョンを調べるべきだとわかります。参照セットは小さく保ち——少数の厳選された画像は大量の不整合な寄せ集めに勝ります——バージョン管理を続けてください。再現性が鍵だからです。

コードベース内でリクエストを組み立てる

参照ベース動画呼び出しのリクエストには、概念的には三つの部分があります：モデル選択、動作を記述するプロンプト、複数画像と音声素材を含む参照ペイロードです。各部をそれぞれのレイヤーに保ち、一つを変更しても他方に触れずに済むようにしてください。

実用的な構造

config/          モデル id、エンドポイント、デフォルトパラメータ
refsets/         バージョン管理された参照素材 + マニフェスト
builder/         プロンプト + 参照セット + パラメータをリクエストに組み立てる
client/          HiAPI 呼び出し、リトライ、エラーマッピング
handler/         返された動画を検証して保存する

この形のリクエストビルダーは概ね次の処理を行います：

1. 設定からモデル識別子（例：vidu-q4-preview/reference-to-video）を読み込む。呼び出し側に埋め込まれたリテラルから決して読み込まない。
2. マニフェストからバージョン指定で参照セットを読み込み、使用した正確な素材を実行とともに記録する。
3. シーン、動作、テンポを記述するプロンプトテキストを添付する。
4. デフォルトパラメータを実行ごとの上書きとマージする。
5. クライアントレイヤーが HiAPI API に送信するリクエストオブジェクトを生成する。

接合部をきれいに保つ

ビルダーだけがリクエスト形状を知っている場所です。フィールド名が変わったり、参照ベース動画モデルがパラメータを追加したりした場合、変更はビルダーに入り、他のどこにも入りません。プロンプトテキストは可変スロット（製品名、シーンビート、行動喚起）を備えたテンプレートであるべきで、呼び出しコードに散らばった文字列連結であってはなりません。

送信前に検証する

ビルダー内で早期に失敗させます：参照セットが解析可能であること、想定数の画像が存在すること、音声が空でないこと、プロンプトが制限範囲内であることをアサートしてください。ローカルで拒否された不正なリクエストはミリ秒で済みます。同じリクエストをリモートで拒否されると往復一回分かかり、計量方法によっては失敗タスクが生成されることもあります。

出所を記録する

送信した各ジョブについて、モデル識別子、参照セットバージョン、プロンプトテンプレートバージョン、パラメータの上書きを記録してください。そのログ行こそが「出力が悪くなった」を答えられる問いに変える鍵です。統合時に HiAPI の公開ドキュメントで現在の識別子とパラメータ名を確認し、モデルをアップグレードする際に再確認してください。

レスポンス処理とショート動画の後処理

返された素材は出発点であり最終成果物ではありません。ショート動画プラットフォームは独自のアスペクト比、尺、ラウドネス規範、字幕慣行を課すため、返された動画とそのネイティブ音声はそれらに合わせて整形する必要があります。

まず保存し、その後変換

返された生動画に触れる前に、永続ストレージに書き込んでください。変換は不可逆で時に欠陥があります。唯一のコピーがトリム済みのものである場合、悪いトリムは再生成を意味します。ストレージオブジェクトのキーにジョブ id と参照セットバージョンを使い、公開したあらゆるクリップをその入力まで追跡できるようにしてください。

後処理チェーン

典型的なショート動画チェーンは次のようになります：

• 検査。返された素材から尺、サイズ、フレームレート、音声ラウドネスを読み取り、ジョブメタデータに記録します。
• トリム。目標尺にカットし、固定オフセットで切るのではなく意図的にイン/アウト点を選びます——生成は冒頭にしばしば一拍の不安定さを残します。
• 再構図。プラットフォームのアスペクト比に合わせてスケールとクロップを行います。主体が中央から外れている場合は、盲目的な中央クロップではなく主体認識クロップを使用します。
• 音声正規化。ネイティブ音声トラックにラウドネス正規化を適用し、音声リファレンスが意図通りに行き渡っていることを検証します。
• 字幕とブランディング。焼き込み字幕やオーバーレイは別ステップとして追加し、ベース動画を再エンコードせずに変更できるようにします。
• エンコード。各ターゲットプラットフォーム向けの最終プロファイルを生成し、中間マスターを保持します。

音声を明示的に扱う

モデルがネイティブ音声を返す場合、音声トラックを独立した成果物として扱ってください。抽出し、測定し、正規化し、再度封装します。これにより生成を再実行せずに静かなトラックを修正でき、同期の問題が早期に可視化されます。

検証失敗時は大声で警告する

後処理後に自動チェックを実行します：尺が範囲内、アスペクト比が正しい、音声が存在しラウドネス下限を超えている、冒頭に黒フレームがない。失敗したものは配信ではなくレビューキューに入ります。ショート動画の量は各クリップの人手レビューを不可能にするため、検証ゲートが不良出力の公開を防ぐ鍵となります。

コスト、遅延、故障モードのチェックリスト

生成はタスク単位で計量され実際の時間を消費するため、運用上の懸念は高価な非同期ジョブと同じです：無駄な実行をどう避けるか、失敗した実行をどう診断するか。参照ベース動画の失敗した実行を調査する際は、以下のチェックリストを使用してください。

入力起因

• 参照セットは解析可能か、意図したバージョンか？
• 画像は主体、スタイリング、カラー処理で一貫しているか？
• 音声リファレンスはクリーンで、音楽や重複音声がなく、空でないか？
• サイズ、形式、サンプリングレートはドキュメントの制限範囲内か？

リクエスト起因

• モデル識別子はドキュメントと完全に一致して綴られており、まだ有効か？
• パラメータ名と値の型はこのモデルに対して有効か？
• プロンプトは長さ制限内か、参照が既にカバーするアイデンティティを再記述するのではなく動作を記述しているか？
• クライアントレイヤーが課す並列数やレート制限を超えていないか？

レスポンス起因

• リクエストは成功したが検証ゲートを通らない素材が返されたか？まずトリムとクリップ冒頭の安定性を確認してください。より長い生成ウィンドウは動作の途中から始まるクリップをしばしば修正します。
• 出力は参照に対してモデルが逸脱しているか？これはほぼ常に参照の一貫性問題であり、プロンプト問題ではありません。
• 散発的なタイムアウトが見られるか？冪等なジョブ追跡を追加し、リトライが二重課金にならないようにしてください。

コストと遅延の衛生

• 盲目的にリトライしない。転送エラーや明示的にリトライ可能な状態でのみリトライしてください。コンテンツ失敗は再び失敗します。
• 入力をローカルで検証する。ローカルで捕捉されたエラーは、いずれも支払いの発生しない実行です。
• 遅延は自分で測定する。数字を仮定するのではなく、自分のワークロード上でモデルとパラメータ構成ごとに送信から準備完了までの時間を記録してください。
• 積極的にキャッシュする。審査済みの出力は多くの下流バリアントに提供できます。参照やシーンが実際に変わったときだけベースを再生成してください。
• 影響範囲を制限する。バッチジョブには最大失敗閾値を設け、系統的障害時にキューを停止させてください。

このリストをログの隣に置いてください。失敗した実行のほとんどは一分以内に上記三つの分岐のいずれかに分類されます。

繰り返し可能なパイプラインに統合する

最後のステップはワークフローをループに変え、テンプレートと参照ライブラリからオンデマンドでショート動画クリップを生成し、審査済みの各出力をライブラリにフィードバックすることです。

ループ

パイプラインには繰り返し実行される四つのフェーズがあります：

1. テンプレート + 参照の選択。テンプレートはプロンプトの骨子、パラメータのデフォルト、後処理設定を保持します。参照ライブラリはバージョン管理された素材セットを保持します。ジョブは両方を一つずつ組み合わせます。
2. 生成。リクエストビルダーが呼び出しを組み立て、クライアントが送信し、返された素材は出所メタデータとともにストレージに格納されます。
3. 審査と後処理。クリップは自動で検証ゲートを通過します。フラグが立ったものは人手レビューに入ります。承認されたクリップはトリム、再構図、音声正規化、エンコードへと進みます。
4. フィードバック。レビューでの構造化されたメモ——「声のドリフト」「照明の不一致」——は、場当たり的なプロンプト編集ではなく参照ライブラリやテンプレートへの変更になります。バージョン番号を上げて変更を追跡可能にしてください。

繰り返し可能にする理由

• プロンプトよりテンプレート。ジョブ間で繰り返されるものは、毎回の実行コードではなくテンプレートに属します。
• すべてをバージョン管理する。参照セット、テンプレート、モデル識別子、後処理設定。ジョブログは実行内容を正確に再構築できるものであるべきです。
• 決定論的なパッケージング。データ——シーンのスプレッドシート、コンテンツカレンダー——からキューを構築し、パイプラインがそれをジョブに展開できるようにしてください。
• レビューをデータとして扱う。レビュー結果を構造化ストレージに記録し、どのテンプレートと参照セットが最も承認済みクリップを生み出すかを測定できるようにしてください。

どこから始めるか

一つのテンプレートと一つの参照セットから始め、小さなバッチを実行し、拡張する前に参照セットを調整してください。パイプラインの価値は参照ライブラリが時間とともに複利で積み上がることから生まれます：承認された各クリップはその背後の素材を検証し、拒否された各クリップは何を修正すべきかを正確に指し示します。

統合の準備ができたら、HiAPI の vidu-q4-preview/reference-to-video に関するドキュメントで現在のモデル識別子とリクエスト形状を確認し、モデル選択を設定に保って、次のモデルリリース後もパイプラインの残りが生き残るようにしてください。