Veo リファレンス画像 API チュートリアル：アセットから動画へ

AI Overview

Veo API は最大何枚のリファレンス画像を使用できますか？

Veo 3.1 では、1 人の人物、キャラクター、または製品に対して最大 3 枚のリファレンス画像を指定できます。関連性のない 3 種類の構図ではなく、同一性、素材、形状を明確に示す、小さく一貫性のあるセットを用いてください。

リファレンス画像は最初と最後のフレームと同じですか？

いいえ。「referenceImages」は被写体やスタイルの一貫性をガイドするものであり、「image」は最初のフレームを設定し、「lastFrame」は終了フレームを制約します。固定したい要素に応じて、いずれか 1 つのモードを選択してください。

どの Veo モデルがリファレンス画像をサポートしていますか？

Google の現行 Gemini API ドキュメントによると、リファレンス画像は Veo 3.1 および Veo 3.1 Fast でサポートされていますが、Veo 3.1 Lite や Veo 3.0 ではサポートされていません。リファレンス画像を用いた生成は、8 秒間の動画長で実行されます。

API 統合時に保存すべきデータは何ですか？

入力アセット ID、正規化済みプロンプト、モデルおよび設定、操作名、最終出力ファイル、レビュー結果を保存してください。この記録により、失敗した生成を再現可能にし、再試行を推測に頼る作業にしないようにできます。

コーディング前にリファレンスモードを選択する

Veo リファレンス画像 API チュートリアル の背後にある実践的な課題は、単に base64 データを送信することだけではありません。開発者は、ショットに最も適した視覚的制御方法、関連付けられるフィールドの組み合わせ、そして製品のディテールが無視されたりキャラクターが想定から逸脱したりした場合の復旧手順を理解しておく必要があります。

本ガイドのために新たに考案されたリファレンスセットの概念。ライダー、サフラン色のジャケット、アンバー色のメガネ、コバルト色のオートバイが明確な連続性のアンカーを提供しています。これは Veo のベンチマークとして提示されているものではありません。

まず、以下の 3 つのモードのいずれかを選びます：

この違いは重要です。referenceImages 内のキャラクターポートレートは、レンダリングされた最初のフレームがそのポートレートをピクセル単位で再現することを保証するものではなく、あくまでガイドです。逆に、開始 image は初期構図を固定しますが、3 種類の異なる同一性ビューは提供しません。プロンプト内で概念を混在させたうえで、API が誤った制約を選んだと非難しないでください。

Google の現行 Gemini API 表によると、referenceImages は Veo 3.1 および Veo 3.1 Fast において最大 3 個の VideoGenerationReferenceImage オブジェクトをサポートしています。Veo 3.1 Lite はこのフィールドをサポートしていません。リファレンス画像を用いたリクエストは 1 本の動画を生成し、8 秒間の動画長を用います。縦型・横型のどちらにも対応し、フル版 Veo 3.1 ルートでは 720p、1080p、4K のいずれかで生成可能です。解像度を上げると遅延とコストが増加するため、配信規模を拡大する前にショット契約を検証してください。

エンドポイントの構築に先立ち、より広範なインターフェースレベルでの説明が必要な場合は、Google Flow および Veo ワークフロー ガイド をご覧ください。

リファレンス画像とプロンプトの準備

一貫性のある単一アセットセットを作成する

同一性について合意が取れたリファレンス画像を用いてください。有用な 3 枚セットの例としては、顔と衣装のクリーンなビュー、製品の形状ビュー、そして必ず残しておきたい小物のビューが挙げられます。色温度、レンズ歪み、比率を互換性のあるものに保ってください。ある画像でコバルト色のオートバイが、別の画像でネイビーの異なるシャシーが描かれていた場合、プロンプトはどちらの形状を基準とするかを信頼ably 判定できません。

キャラクターリファレンス：顔の輪郭、髪のシルエット、ジャケットのパネル、アンバー色のレンズを確認してください。ドラマチックだが見えにくいポートレートよりも、読み取りやすいリファレンスの方が有用です。

製品リファレンス：完全なホイール形状、フレームのシルエット、コバルト色のパネル、ジャケット、メガネが、雨上がりのニュートラルな光の下で明瞭に確認できます。

有料リクエストの前に画像を前処理してください。MIME タイプを確認し、空ファイルを拒否し、一度だけデコードして破損を検出し、パイプラインが意図的にトリミングしない限り元のアスペクト比を維持してください。チェックサムと内部アセット ID を保存してください。base64 はリクエストサイズを増加させるため、可視ディテールをすべて保持できる適切なサイズの派生画像があるのに、過大なマスターファイルを繰り返しエンコードしないでください。

保持を意識したプロンプトを書く

優れたプロンプトは、Veo に対して「何が起こるか」と「何を安定して保持すべきか」を明確に伝えます。以下の再利用可能な順序で記述してください：

中距離トラッキングショット。銀髪のライダーがサフラン色のジャケットを着用し、マットなコバルト色のオートバイで、日の出時の濡れた海岸沿いの道路を走行します。彼女の顔、ショートボブのシルエット、アンバー色のビジュアルメガネ、ジャケットのパネル、オートバイのボディ形状、ホイール数、コバルト色の仕上げを保持してください。波しぶきは自然に動き、カメラは平行にトラッキングし、旋回しません。自然な風音、タイヤ音、遠くの波音のみ；会話なし、テキストなし、ロゴなし。可視的な特徴（外見的特徴）に基づいて参照画像を識別し、ファイル名ではなく「誰／何が写っているか」で呼称してください。8秒間のショットごとに、主なアクションは1つ、カメラ動作も1つに限定してください。「固定カメラ」と「高速オービット」など、互いに矛盾する指示は、参照画像では解決できない調整困難を引き起こします。画像から動画を生成するプロンプト作成ガイドには、再利用可能な「被写体－アクション－カメラ－保持」の簡潔なパターンが記載されています。

Veo 3.1 リクエストを送信する

JavaScript でアセット参照を作成する

現在の @google/genai SDK を使用する場合、各準備済み画像を imageBytes と mimeType を含むオブジェクトとして表現し、さらに referenceType: 'asset' でラップします。この SDK はAPIキーを環境変数から読み込みます。APIキーはサーバー側にのみ配置し、ブラウザ内の JavaScript には絶対に含めないでください。

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const assets = [riderImage, motorcycleImage, glassesImage].map((image) => ({
  image,
  referenceType: 'asset',
}));

let operation = await ai.models.generateVideos({
  model: 'veo-3.1-generate-preview',
  prompt,
  config: {
    referenceImages: assets,
    aspectRatio: '16:9',
    durationSeconds: 8,
    resolution: '720p',
  },
});

フィールド名は Gemini API と Vertex AI のインターフェース間で異なる場合があるため、実際にデプロイするエンドポイントに対応した公式ドキュメントを確認し、SDK のバージョンを明確に固定して検証してください。サードパーティ製ラッパーのJSON構造をGoogleのエンドポイントにそのままコピーしないでください。Base64ペイロード全体ではなく、機密情報を除外したリクエストマニフェストをログ出力してください。

最初の受入テストには720pを使用してください。被写体の同一性、動き、カメラ動作、音声の各項目が合格した後、承認済みの設定を、必要な配信解像度で再実行します。アプリケーションが複数のプロバイダー間でルーティングされる場合は、アグリゲーター方式とダイレクトAPI方式の比較ガイドを参照してください。プロバイダー固有のUIメモリよりも、正規化されたジョブ記録の方が信頼性が高い理由が説明されています。

出力のポーリング、ダウンロード、保存

Veo 動画生成は非同期処理です。初期呼び出しでは完成済みMP4ではなく、長時間実行されるオペレーション（操作）が返されます。適切な間隔でオペレーション名によるポーリングを行い、事前に定めたタイムアウトで停止します。また、ワーカー再起動時に重複ジョブを送信せず、処理を再開できるよう、オペレーションIDを永続化してください。

while (!operation.done) {
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  operation = await ai.operations.getVideosOperation({ operation });
}

const generated = operation.response.generatedVideos[0];
await ai.files.download({
  file: generated.video,
  downloadPath: `outputs/${jobId}.mp4`,
});

Googleは現時点で生成された動画を自社サーバー上に2日間保持しています。そのため、速やかに自社管理のストレージへダウンロードしてください。ファイルが存在し、ゼロでないサイズを持ち、動画として正常にデコード可能であることを確認し、期待通りの再生時間を満たしていることも検証してください。レビュー用にポスターフレームを保存するのは良いですが、ポスターフレームが表示できることをもって、全動画の品質が保証されていると誤解しないでください。

Veo 3.1 シネマティック動画の例（フルクリップ検査用）

被写体の同一性、環境、カメラ動作、音声の連続性を確認するため、動画全体を通常速度で視聴してください。1枚の魅力的なフレームが隠す不具合は、動画全体を再生することで明らかになります。

一貫性の検証と障害対応

固定された受入グリッドでレビューする

各出力を通常速度で確認し、さらに最も複雑な動きの周辺でも再度確認してください。以下の基準を毎回同一に適用し、「合格」「修正依頼」「却下」のいずれかを記録します：

この代替構図は時間帯とフレーミングを変更していますが、同一の連続性アンカー（continuity anchors）を維持しています。このようなフレームを用いて、シーン変更後でもアセットの同一性が保たれているかを評価できます。

すべての出力で同じ特徴が失われる場合、参照画像またはプロンプトの階層構造に問題がある可能性が高いです。一方、失敗がランダムに発生する場合は、まず入力を固定したまま再実行し、すべてを書き直す前に原因を特定してください。構図の終了位置を厳密に設計済みの画像と一致させる必要がある場合は、referenceImages に追加の保持言語を加える代わりに、image と lastFrame を併用するように切り替えてください。

Seedance 製品モーション出力（幾何学的正確性および制御されたカメラ挙動の比較用）

これは異なるモデルおよびショットタイプによる出力であり、Veo のベンチマークではなく、実際の動きをレビューするための具体例として掲載しています。同様の幾何学的およびカメラ評価基準を適用してください。

プロバイダー由来のエラーと創造的な失敗を明確に区別してください。認証エラー、クォータ制限、無効なMIMEタイプ、サポートされていない設定、セーフティフィルタリング、タイムアウト、および完了したが使用不能なクリップは、それぞれ異なる対応が必要です。一時的な通信障害またはサービス障害のみを自動再試行対象とし、拒否されたプロンプトや視覚的に不適切な結果は、人手によるレビューに戻すべきです。課金が発生する無限ループには絶対に入れないでください。最終エクスポートの前に、AIビデオのフレームレートガイド を参照して納品頻度（デリバリー・ケイデンス）を確認してください。生成時の24 fps設定とプラットフォーム側の納品設定は関連していますが、相互に置き換え可能な決定ではありません。

Seedance Agent ワークフローに組み込む

生の Veo API は、開発者がすでにアセットのストレージ管理、プロンプトのバージョン管理、操作のポーリング、承認フロー、および再試行ポリシーを自社で運用している場合に適しています。一方、実際のタスクが1回のAPI呼び出しを超えて複数のステップにわたる場合（例： brief からショットリストを作成し、参照役割を割り当て、各ショットごとにサポート対象モデルを選択し、実際の出力をレビューし、失敗したセグメントのみを再実行する）、Seedance Agent の活用が有効です。

ライダーのシークエンスの場合、エージェントはポートレート、オートバイ、眼鏡の3つのアセットを1度だけ登録し、沿岸部を追跡するショットとブルーアワーのエンディングを別々のジョブとして作成できます。また、両者の保存ルールを整合させ、両方のクリップを承認用に公開することも可能です。このとき、APIはあくまで生成レイヤーとして機能し、エージェントが制作状態（production state）を管理します。これにより、意図しない重複リクエストが減り、後工程でのプロンプト編集が、無意識のうちに正規アセットセットを変更してしまうリスクも防止できます。

コスト評価は「承認済み秒数あたりのコスト」で行い、「完了したリクエスト数」で評価しないでください。アイデンティティの安定性、実用可能なエンディングの有無、レビュー所要時間、再実行回数といった観点から、Veo 3.1 を他の手法と比較するには、Seedance 2.5 対 Veo 3.1 比較記事 をご参照ください。目的は、すべてのショットを単一モデルで強制的に処理することではなく、回避可能な修正を最小限に抑えながら、一貫性のあるシークエンスを確実に納品することです。

結論

信頼性の高い Veo 参照画像API統合は、まず適切な制御モードを選択し、最大3点の整合性のあるアセット参照を準備し、明確なモーションと保存要件を含むプロンプトを1つ作成し、有効な Veo 3.1 リクエストを送信し、長時間実行される操作を永続化し、保持期間の満了前にダウンロードし、固定された評価基準（rubric）でフルクリップをレビューすることから始まります。一時的なAPI再試行とクリエイティブな再実行は分けて管理し、正確な開始・終了フレームが柔軟なアセットガイドよりも重要となる場合は、最初と最後のフレーム間の補間（first-and-last-frame interpolation）に切り替えてください。プロジェクトにおいてショット計画、共有参照、モデルルーティング、承認、およびAPI呼び出し周辺での選択的再実行が必要な場合は、ワークフローを Seedance Agent → から始めることをおすすめします