Gemini Omni 1.2 Flash APIで動画を生成・ダウンロード・検証する方法
完全なPythonサンプルでGemini Omni 1.2 Flashを利用。ファイルの待機、ダウンロードの復旧、動画検証と、参照素材・編集・延長の制限を解説します。
gemini-omni-1.2-flash をGoogleのInteractions APIから呼び出し、動画出力を指定したうえで、インタラクションの完了、動画ファイルの準備、ダウンロード後の検証を別々に確認します。 APIが完了を返しても、再生できる動画を手元に保存できたとは限りません。ファイル処理中に再生成すると、不要な処理や料金が増える可能性があります。
この記事では小さなテキストからの動画生成を例に、取得までの手順をたどります。実行用Pythonプログラム、復旧コマンド、ローカルのメディア検証器を配布し、参照素材、編集、延長で設定がどう変わるかも説明します。公式資料の確認日は 2026年11月15日 です。
発行元はOfoxです。検証したのは、合成レスポンスと実際のGoogle SDKを使った 24件のヘルパー・実行プログラムのオフラインテスト と、独自にFFmpegで生成した素材を使った 10件のメディア検証テスト です。実際のOmni生成、画質比較、レイテンシー測定、請求額の検証は実施していません。配布するオンライン実行用プログラムはオフライン検証済みの接続テンプレートであり、Googleへの実呼び出しが最後まで成功したという意味ではありません。合成テスト動画をOmniの生成物として掲載することもありません。
本文で参照するGoogleの公式ドキュメントは英語です。
最初にモデルとAPIの経路を決める
現在の Googleのモデル仕様には gemini-omni-1.2-flash が掲載され、テキスト・画像・動画を入力し、動画とネイティブ音声を出力できます。テキスト専用のGeminiモデルや、以前のVeoリクエスト形式に置き換えないでください。既存の Veo 3.1 APIチュートリアル (英語)は別モデルの接続を扱っています。
モデルへのアクセス権があり、必要な課金または利用枠が設定されたGoogleプロジェクトを用意します。キーの取得と管理は GoogleのAPIキードキュメントを確認してください。一般向けアプリの契約だけで、APIプロジェクトから呼び出せるとは判断できません。通常のシークレット管理手段で GEMINI_API_KEY を設定し、プロンプトや公開ログには書き込まないでください。
ここではGoogleの https://generativelanguage.googleapis.com/v1beta/interactions を使います。Ofoxには別仕様の動画タスクAPIと、タスク作成、状態取得、認証の説明があります。Ofoxが対応する動画モデルを利用する際には役立ちますが、下記のGoogleリクエストと交換できる仕様ではありません。この記事でOfoxのOmni対応を確認したことにはならず、OfoxのOmni料金も提示しません。

Googleの英語版公式ドキュメントの実際の画面です。アカウント情報を除いて切り抜いています。生成結果やOfox接続テストの画面ではありません。
Googleは gemini-omni-1.1-flash の接続先を1.2に変更する日を 2026年12月3日 としています。この記事の確認日時点ではまだ先の日付です。この例では将来の別名変更に依存せず、1.2を明示します。モデル仕様では gemini-omni-flash-preview は停止済みです。
配布キットを入れ、オフラインで確認する
Omni動画キットをダウンロードし、展開した omni-video-kit ディレクトリに移動します。オンライン実行用プログラム、結果処理ヘルパー、メディア検証器、2つのテストモジュール、英語READMEが入っています。断片的なコードから主プログラムを組み立てる必要はありません。
Python 3.11以降 と独立した環境を使います。
python -m venv .venv
source .venv/bin/activate
python -m pip install 'google-genai==3.3.0' httpx
python -m unittest test_video_result.py test_runner_offline.py -v
Windows PowerShellでは .venv\Scripts\Activate.ps1 で有効化します。パッケージのインストールはレジストリに接続します。一方、テストは合成データとモックを使い、実行プログラムのテストではネットワーク接続も遮断するため、Googleキーは不要です。期待する結果は 24件のテスト成功 です。
ヘルパーではインタラクションの完了・未完了、URI、ファイル状態、回数制限付きポーリングを確認します。実行プログラムではSDKが実際に送信する形式、GETによる復旧、タイムアウトやサービスエラー、部分ダウンロードの保全、並行して作られた出力の上書き防止を検証します。モックの503やタイムアウトで作成POSTが1回だけになり、自動再送されないことも確認します。
メディア検証器は別の検査です。信頼できるパッケージマネージャーまたは公式配布元から ffmpeg と ffprobe を入れ、実行できることを確認してください。検証には生成パターンや音、無音トラック、破損ファイル、意図的に異なるトラック時間を使いました。これが検証するのはチェッカーであり、モデルの生成品質ではありません。
設定を固定して短い動画を生成する
最初は主体を1つ、動きを1種類、カメラを固定にすると、指示に合うか判断しやすくなります。プログラムの英語プロンプトは次の内容です。
1枚の緑の葉が静かな池を左から右に漂う。固定のワイドショット、柔らかな日光。静かな自然の水音。話し声、音楽、文字は入れない。
目標は自然な水音のある 3秒、横長、720pの動画 です。これは要求する結果であり、実際に観測した生成物ではありません。配布プログラムの作成呼び出しは次のとおりです。
interaction = client.interactions.create(
model="gemini-omni-1.2-flash",
input=(
"A single green leaf drifts across a still pond from left to right. "
"Fixed wide shot, soft daylight. Quiet natural water sounds, "
"no speech, no music, no text."
),
response_format={
"type": "video",
"delivery": "uri",
"duration": "3s",
"resolution": "720p",
"aspect_ratio": "16:9"
},
store=True,
timeout=180,
automatic_continuation=False
)
この抜粋は run_live.py のクライアントと復旧処理を前提にしています。実行には完全なスクリプトを使ってください。HTTPタイムアウトと retry_options.attempts=1 を設定してSDKの自動再試行を止め、送信前にローカル復旧記録を確保します。サーバー側の結果が不明なときの重複作成を避ける措置であり、どんなインフラでも必ず1回だけ実行される保証ではありません。
自分のGoogleプロジェクトキーを設定してから次を実行すると、実リクエストが送られ、利用枠や料金を消費する可能性があります。
python run_live.py --create --out leaf.mp4
store=True は、後から結果を取得し、編集会話にも使うために選んでいます。Omniの公式ガイドには保存しない同期の単発生成もあります。ただしその場合、後で previous_interaction_id による編集を続けられなくなります。復旧を前提とするこの例に、その設定を無条件で移さないでください。
URI方式なら大きな動画をJSONレスポンスに収める必要がありません。ただし、すべての生成をバックグラウンドにする必要があるという意味ではありません。生成方式、インタラクションの完了、ファイルの準備は別の問題です。次では、待ち時間のたびに再生成するのではなく、プログラムが扱う状態を区別します。
インタラクションの完了、ファイルの準備、取得の復旧を分ける
レスポンスが届くと、プログラムは leaf.mp4.interaction.json を保存し、インタラクションIDと状態を表示します。この記録には内容やメディア情報が含まれる可能性があるため非公開で保管してください。記録があるだけでは完成した動画の証明にはなりません。
| 段階 | プログラムの確認 | 保管するもの・次の操作 |
|---|---|---|
| 作成送信済み、結果不明 | IDがなくても確認待ち記録がある | 再作成前にアカウントや提供元の記録を調べる |
| インタラクションが返った | completed、エラーなし、動画出力あり | IDとレスポンスを保存する |
| URIで動画を受け取った | 想定したGoogleファイルのURIである | そのファイルを確認する。新規タスクIDとは扱わない |
| ファイル処理中 | PROCESSING、ACTIVE、FAILED | 処理中は待機、ACTIVEで取得、失敗・未知状態なら停止 |
| ダウンロード中 | 新しい .part に書き込む | 失敗時に部分データを残し、完成品として使わない |
| ローカル保存確定 | 空でなく、既存出力を置き換えていない | メディアと内容の受け入れ確認を行う |
ヘルパーは公式のHTTPS Googleファイルのオリジンとリソースパスだけを受け付けます。/v1beta/files/...:download?alt=media のようなURIを、Files APIが必要とする files/... 名に変換します。認証情報付きURLや別のサイトは拒否し、出力中の任意リンクを取得しません。認証はSDKが処理するため、コピーするダウンロードURLにキーを含める必要はありません。
ファイル確認は最大 60回、間隔は 5秒、HTTPタイムアウトは 180秒 です。ポーリング回数と各リクエストの時間制限であり、総時間が必ず5分以内になる期限や生成速度の保証ではありません。通信エラーは呼び出し元に返し、再作成を開始しません。現在の実装はSDKの最初の動画を選びます。複数出力を扱うなら変更してテストしてください。
既存のインタラクションを取り直すには、実際に返ったIDを使います。
python run_live.py --resume YOUR_INTERACTION_ID --out recovered-leaf.mp4
これは作成POSTではなく取得GETです。未完了のインタラクションを自動で継続ポーリングするわけではないので、保存状態を見て必要なら後で再取得します。最初の通信がIDの受信前にタイムアウトした場合、未知のサーバー処理をこのスクリプトから探すことはできません。確認待ち記録が同じ出力名での再作成を止めます。名前を変えてこの保護を回避せず、元のリクエストを調べてください。
出力または .part が既にあると、送信前に停止します。ダウンロード失敗時は部分ファイルと復旧記録を残します。存在が分かっているインタラクションを復旧するときは、上のように新しい出力名を指定します。最終保存は同じディレクトリのハードリンクを作ってから .part を削除し、並行して作られた出力を上書きしません。対応しないファイルシステムでは完全な部分ファイルを保持して保存処理を直してください。ローカルの保存問題のために動画を再生成する必要はありません。
ファイルを検査してから、映像と音を確かめる
保存が報告されたら、ローカルのメディアを検証します。
python verify_video.py leaf.mp4 --seconds 3 --require-audio
空でないファイル、有効な寸法の通常の動画ストリーム、正の時間、指定時には音声ストリームを要求します。コンテナと各通常動画トラックの長さを、このサンプル用に決めた0.25秒の許容差で確認し、FFmpegで動画と音声をデコードします。トラック時間のメタデータが欠けている場合は、コンテナの時間で代用せず厳密検査を失敗にします。
この区別は重要です。3秒のコンテナでも、映像は1秒で音声だけ3秒という場合があります。コンテナだけの検査では短い映像を見逃します。また、音声ストリームがあっても無音かもしれません。検証器が確認するのは存在であり、聞こえる音、同期、表現の良さではありません。
葉のサンプルでは、別途次を見て聴いて確認します。
| 確認事項 | 見る・聴く内容 | 不合格の場合 |
|---|---|---|
| 主体は合っているか | 池の緑の葉が1枚で、無関係な主体がない | 主体の条件を1つ変更して試行を記録 |
| 動きは合っているか | 葉は左から右、カメラは固定 | 主体とカメラの動きを別々に指定 |
| 連続した映像か | 不意のカット、ちらつき、唐突な終わりがない | 編集や再生成前に始点・中間・終点を比較 |
| 音は使えるか | 水音が聞こえ、不要な声や音楽がない | 実際に聴く。音声トラックだけで合格にしない |
| 使用先に合うか | 必要な構図、明瞭な主体、余計な文字がない | メタデータだけでなく使用先の表示で確認 |
実際の葉の動画を生成・採点したわけではありません。許可された実行時に使える具体的な基準です。プロンプト、正確な設定、結果を一緒に残せば、次の試行と比較できます。デコード成功は技術的な節目であり、指示に従った証拠とは別です。
参照素材、編集、延長を用途ごとに設定する
モデル仕様と用途別の制限はモードごとに異なります。新規生成の最長時間をすべての操作に使わないでください。
| 操作 | 公式の範囲 | 実装時の注意 |
|---|---|---|
| 新規動画 | 3〜15秒の整数秒、既定10秒 | 再現できるサンプルは時間を明示 |
| 最初と最後のフレーム | 3〜10秒 | 2枚の端点画像から15秒の補間はできない |
| 画像参照 | 各時間で最大6枚 | 各画像の役割を明確にする |
| 新規生成の動画参照 | 出力3〜10秒は最大3本、11〜15秒は1本。各参照は最大3秒 | 参照本数と出力時間を別に数える |
| 編集する入力動画 | 最大15秒 | 不適切な入力は先に分割・トリミング |
| 延長 | 1回3〜10秒、合計30秒まで。文脈は末尾10秒 | 合計時間を記録し、以前の重要情報は再提示 |
| 解像度 | 360p、720p、1080p、4k。既定720p | 1080pと4Kはアップスケールと記載され、ネイティブ撮影とは呼ばない |
画像から何を維持し、動画を新しいショットにどう反映するかは自然言語で説明します。参照動画の音声は無視され、動画参照は編集・延長ではなく新規生成用です。ネイティブ音声の出力は、アップロード音声や音声参照の入力対応を意味しません。声の編集も未対応です。
Googleは複数動画をまたぐ参照・推論も未対応とし、複数動画のプロンプトで品質低下や予期しない結果が出る可能性を示しています。参照本数の上限は、動画横断推論の信頼性を保証しません。
最初の画像参照では、古い制御タグより具体的な役割を指定します。
Create a 5-second landscape shot.
Use the attached image as the appearance reference for the green leaf.
Keep its shape and color consistent.
The leaf drifts from left to right across still water.
Keep the camera fixed, with soft daylight and gentle water sounds.
Do not add speech, music, captions or extra leaves.
このテンプレートは、5秒の横長動画、添付画像の葉の形と色の維持、右向きの移動、固定カメラ、日光と水音、声・音楽・字幕・余計な葉を追加しないことを指定します。ただし、画像は公式のメディア入力形式で実際に添付する必要があります。「添付画像」と書くだけではアップロードされません。素材を使う権利と、アカウントでその操作が可能かも確認してください。Googleは video_config.task を強制する前に自然言語の明確な役割指定を勧めています。強制指定では素材の組み合わせがより厳しくなる場合があります。
既に生成して保存した動画を編集する独立した例です。edit_saved_video.py として保存し、実際の前回IDを OMNI_PREVIOUS_INTERACTION_ID から読みます。別の課金対象になり得る操作であり、オフラインテストやダウンロード復旧ではありません。
import os
from pathlib import Path
from google import genai
client = genai.Client(
api_key=os.environ["GEMINI_API_KEY"],
http_options={"timeout": 180000, "retry_options": {"attempts": 1}}
)
try:
edit = client.interactions.create(
model="gemini-omni-1.2-flash",
previous_interaction_id=os.environ["OMNI_PREVIOUS_INTERACTION_ID"],
input="Make the daylight warmer. Keep the leaf, its motion and the camera framing unchanged.",
response_format={"type": "video", "delivery": "uri"},
store=True,
timeout=180,
automatic_continuation=False
)
Path("edit-interaction.json").write_text(edit.model_dump_json(indent=2))
print(edit.id, edit.status)
finally:
client.close()
同じ有効化済み環境とキットのディレクトリで GEMINI_API_KEY を設定したまま、編集したい保存済み生成のIDを指定します。macOSまたはLinuxでは次のとおりです。
export OMNI_PREVIOUS_INTERACTION_ID='YOUR_STORED_GENERATION_ID'
python edit_saved_video.py
Windows PowerShellでは $env:OMNI_PREVIOUS_INTERACTION_ID = 'YOUR_STORED_GENERATION_ID' を設定し、python edit_saved_video.py を実行します。プレースホルダーを生成のインタラクションIDに置き換えてください。Files APIのリソース名ではありません。edit-interaction.json は非公開とし、再実行前に各試行の記録を保管します。
レスポンスが返ったら、その新しいIDを run_live.py --resume に渡し、新しい出力名で取得してメディア・目視検証を繰り返します。この短い編集例は、配布する初回生成プログラムと違ってPOST前の確認待ち記録を確保しません。IDなしでタイムアウトしたら、編集されなかったと決めつけず、アカウント記録を調べてから再実行してください。記事のためにこの編集や実際の延長は行っていません。
アップロード動画の編集・延長にはEEA、スイス、英国の地域制限があり、モデル生成動画の場合とは異なります。延長は末尾への追加だけで、途中や先頭には追加できません。既に話し声があるアップロード動画への台詞追加も制限されます。一方、以前生成した動画の複数ターンでの音声延長は別に説明されています。操作別の制限を確認し、「動画編集対応」を全操作が可能という意味に広げないでください。
失敗した段階に合わせて調べる
正確なモデル、エンドポイント、SDKバージョン、機密情報を除いたエラー本文、インタラクションIDまたはファイルIDを集めます。既存の Gemini 4 APIエラーガイドは認証、アクセス、リクエスト形式、利用枠を切り分けます。ただしモデル別の例はArgonなので、ここではOmniのIDと動画形式を維持してください。
| 症状 | 調べる段階 | 次の対応 |
|---|---|---|
| HTTP 200でも動画を解析できない | レスポンス形式・未完了状態 | SDKの output_video は便利な属性。RESTでは動画は steps 内にある |
| 最初・最後のフレームで時間エラー | 操作別の制限 | 同じ無効リクエストを再送せず、対応する時間に変更 |
| 生成設定が拒否される | 未対応のパラメーター | システム指示、temperature、top_p、停止シーケンス、独立した否定プロンプトを除き、通常のプロンプトに条件を書く |
| インタラクションは完了、ファイルは処理中 | ファイルの準備 | 新規生成せず同じリソースを確認 |
FAILED または未知のファイル状態 | 処理失敗・形式変更 | 証拠を残して停止。「処理中以外」をすべて成功にしない |
| タイムアウトで作成結果が不明 | 通信とサーバー実行の違い | 確認待ち記録を保持し、次のPOST前に調査 |
| 取得成功でも検証に失敗 | バイト列、トラック、ローカルツール | 検査結果を見て、再取得か再生成かを判断 |
| アップロード動画の操作が使えない | 地域、素材の種類、ポリシー | 無闇に認証情報を変更せず操作条件を確認 |
安全フィルターによる拒否は、許可された範囲で内容を変更してください。同じ拒否プロンプトの再送では解決しません。期限付き・認証情報付きURLを公開例に使わないでください。Ofoxの別仕様を使うアプリでは動画エラーコードと一般的な再試行ガイドを参照しますが、Googleのエラー仕様の代わりにはなりません。
規模を広げる前にタスクの記録を残す
実際の試行ごとに、モデルID、プロンプト版、参照素材、時間、解像度、比率、保存設定、インタラクションID、ファイルリソース、出力ハッシュ、検証結果を記録します。共有レポートにキーや非公開内容を含めないでください。既存処理を取得するGETと新規処理のPOSTを区別しないと、障害調査も費用分析も不正確になります。
費用を見積もる前に、モードと解像度に合う現在の Omni料金を確認してください。この記事には実測請求額やOfox料金はありません。使用量が分かる失敗、編集、延長は別々に記録し、不明をゼロにしないでください。短い試作でも複数回の有料修正で合計が増えることがあります。単一リクエストより、受け入れられた最終成果までの工程で比較します。
まず小さなサンプルを合格させ、画像参照、別の比率、保存動画の編集、延長を1つずつ加えます。以前の動く設定を比較用に残してください。実アカウントで必要な動画を生成・取得・検証できてから規模を広げます。完成品は利用できる動画と検証記録であり、「生成完了」というメッセージだけではありません。


