AIツール

Veo 3.1 API 動画生成ガイド：開始・終了フレーム、参照画像、4K、非同期ポーリング

Veo 3.1 Gemini API によるテキスト・画像からの動画生成、開始／終了フレーム、参照画像、動画延長、4K、非同期処理とダウンロードを解説します。

Veo 3.1 は Gemini API に加わり、テキスト、画像、既存のビデオを入力としてサポートし、オーディオ付きビデオをネイティブに生成します。 MP4 を同期的に返す通常のインターフェイスの代わりに、最初に長時間実行オペレーションを作成し、次にステータスをポーリングして結果をダウンロードします。 この記事では、この非同期モデルに従ってコードを整理し、最初と最後のフレーム、参照画像、ビデオ拡張子、解像度、および再生時間の間の制限について説明します。

Veo 3.1、Fast または Lite を最初に選択してください

現在、正式に Veo 3.1、Veo 3.1 Fast、および Veo 3.1 Lite ルートを提供しています。 標準バージョンは、画像の一貫性、複雑なショット、高品質の実験に適しています。 高速バージョンは、対話型プレビューやプロンプトのバッチスクリーニングに適しています。 Lite は低コストと高速な制作を目指していますが、機能セットは最高解像度と同じではない可能性があります。 モデルはまだプレビュー段階にある可能性があり、運用システムはモデル ID をロックし、インターフェイス フィールドの変更を受け入れる必要があります。 コンソールに「Veo 3.1」とだけ書くのではなく、コードでは現在公式ドキュメントに記載されている完全なモデル名を使用する必要があります。

個々のパラメータよりもパラメータの組み合わせが重要

Veo 3.1 は 4、6、または 8 秒で利用可能になります。 1080p、4K、リファレンスまたはビデオ拡張機能を使用する場合は、通常 8 秒かかります。 アスペクト比は 16:9 および 9:16 をサポートします。 ビデオ拡張機能は現在 720p のみを出力します。 リクエストごとに 1 つのビデオが生成されます。 フレームレートは24fpsです。 seed は類似性を向上させますが、完全な確実性は保証しません。 送信する前にパラメータ マトリックスを確認すると、失敗を受け取るまでの待機時間を分単位で短縮できます。

APIキーとPython環境の準備

Gemini API キーを使用して Google AI Studio でプロジェクトを作成します。 キーには環境変数のみが含まれます:

1

$env:GEMINI_API_KEY = Read-Host "Gemini API key"

独立した仮想環境を作成します:

1
2
3
4

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install google-genai pillow

パッケージのバージョンを確認します:

1

python -m pip show google-genai

プレビュー API が変更されると、「昨日も実行されていた」という情報よりも、バージョン情報の方がトラブルシューティングに役立ちます。

最初のテキスト生成ビデオ リクエスト

次の構造は、公式 SDK の現在のインターフェイスに基づいています。モデル ID は、実行前にドキュメントで確認する必要があります:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

import os
import time
from pathlib import Path

from google import genai
from google.genai import types

client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt=(
        "A quiet railway platform at dawn, light fog, "
        "slow dolly movement, realistic ambient sound, no text"
    ),
    config=types.GenerateVideosConfig(
        aspect_ratio="16:9",
        resolution="720p",
        duration_seconds=4,
    ),
)

while not operation.done:
    print("waiting", operation.name)
    time.sleep(10)
    operation = client.operations.get(operation)

video = operation.response.generated_videos[0].video
client.files.download(file=video)
video.save("veo-output.mp4")
print(Path("veo-output.mp4").resolve())

SDK フィールドはプレビューで更新される場合があります。属性が存在しない場合は、まずインストールされているバージョンに対応する公式の例を確認してください。

ポーリング間隔が短すぎない理由

ビデオの生成には、テキスト応答よりも時間がかかります。 毎秒ポーリングしてもビデオが早く完了するわけではありませんが、API リクエストとスロットリングの可能性が高まるだけです。 公式の REST 例では 10 秒間隔が使用されており、これが適切な開始点です。 運用タスクでは指数バックオフを使用できますが、最大間隔と合計タイムアウトを設定します。 操作名をデータベースに保存すると、プロセスが再起動された後もクエリを続行できます。 操作オブジェクトをメモリ内にそのまま残さないでください。

HTTP リクエストをブロックする代わりにタスクの状態を保存

Web アプリケーションは生成リクエストを受信すると、まず自身のジョブ ID を返します。 バックグラウンド ワーカーは Veo 操作を送信し、マッピングを保存します:

1
2
3
4
5
6
7

{
  "job_id": "video_20260728_001",
  "operation_name": "operations/example",
  "status": "running",
  "model": "veo-3.1-generate-preview",
  "created_at": "2026-07-28T12:00:00Z"
}

フロントエンドは、Gemini キーや完全な操作データを直接公開することなく、独自のジョブ エンドポイントをクエリします。 ワーカーがクラッシュした後、operation_name を読み取り、ポーリングを続行します。

画像生成ビデオは最初のフレームを使用

最初のフレームはビデオの構成を決定します。 被写体がはっきりしていて、エッジがそのままで、透かしや不要なテキストがない画像を選択してください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from PIL import Image

first_frame = Image.open("first-frame.png")

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt="The camera slowly moves closer while leaves sway in the wind",
    image=first_frame,
    config=types.GenerateVideosConfig(
        aspect_ratio="16:9",
        resolution="720p",
        duration_seconds=8,
    ),
)

画像のアスペクト比が出力と大きく異なる場合、モデルはエッジを切り取るか埋める必要があります。 最初にキャンバスをローカルで 16:9 または 9:16 に処理すると、通常はより制御しやすい結果が得られます。

最初のフレームと最後のフレームが補間トランジションに使用されます

Veo 3.1 は、開始画面と終了画面の指定をサポートしています。 最後のフレームは独立した参照ピクチャではなく、ビデオが最終的に遷移するピクチャです。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

first_frame = Image.open("start.png")
last_frame = Image.open("end.png")

operation = client.models.generate_videos(
    model="veo-3.1-generate-preview",
    prompt="A smooth cinematic transition from morning to night",
    image=first_frame,
    config=types.GenerateVideosConfig(
        last_frame=last_frame,
        aspect_ratio="16:9",
        resolution="1080p",
        duration_seconds=8,
    ),
)

2 つの画像内の被写体の位置の差が大きすぎる場合、トランジションを完了するためにモデルが変形する可能性があります。 キーワードを追加するよりも、最初にカメラ アングル、被写体のスケール、水平線を調整する方が効果的です。

キャラクターまたは商品を維持するために使用される参考画像

Veo 3.1 では、最大 3 つのアセット参照イメージを使用できます。 参考画像は、同じキャラクター、製品、またはスタイルについてさまざまな視点を与えるのに最適です。 3枚の写真の服装、色、比率が矛盾していると、一貫性が低くなります。 製品画像を使用する場合は、完全なアウトラインを維持し、ブランド テキストを背景テクスチャとして使用することは避けてください。 参照画像、1080p または 4K リクエストには、8 秒という公式制限が適用されます。 Lite モデルが対応する参照画像タイプをサポートするかどうかは、現在のパラメータ テーブルに従うものとします。

4K は、720p パラメータを文字列

に変更することを意味するものではありません 4K には、8 秒の継続要件を持つ標準 Veo 3.1 ルートが必要です。 ビルド時間、ダウンロード サイズ、後処理リソースが増加します。 最初に Fast または 720p で映像を確認し、キューワードを通過すると 4K を生成します。

1
2
3
4
5

config = types.GenerateVideosConfig(
    aspect_ratio="16:9",
    resolution="4k",
    duration_seconds=8,
)

縦向き 4K が現在のモデルと地域で利用できるかは、実際の API 応答と公式の対応表で確認してください。 大量送信の前に、必ずパラメーターの組み合わせを少数のリクエストで検証します。

プロンプトの言葉で画像と音声の両方を説明しましょう

Veo 3.1 はオーディオをネイティブに生成し、プロンプトの言葉で周囲の音、会話、音楽の雰囲気を説明できます。 プロンプトには、少なくとも被写体、動作、場面、カメラワーク、照明、音を含めます。

1
2
3
4
5

A close-up of a ceramic cup on a wooden table.
Steam rises slowly while rain hits the window behind it.
The camera performs a gentle clockwise orbit.
Warm indoor light, shallow depth of field.
Audio: soft rain, distant thunder, no speech, no music.

「シネマティック」はカメラの動きや構図の指示に代わるものではありません。 文字が不要な場合は no text と明記しますが、生成後の映像確認は必要です。

ビデオ拡張機能では、Veo で生成されたビデオのみを使用できます

拡張入力は、任意の MP4 アップロードではなく、以前に生成された結果の Video オブジェクトです。 拡張機能は最後の 1 秒、つまり約 24 フレームを使用してアクションを継続します。 元のビデオの最後の 1 秒で音声がない場合、通常は音声を自然に続けることができません。 続けたいアクションとサウンドを最後に置き、次の段落を求めます。 拡張出力は現在 720p のみをサポートしています。 複数の拡張を行うと、視覚的および音声的なずれが蓄積されるため、長編映画では編集ソフトウェアでショットを管理する必要があります。

REST リクエストのコアはオペレーション名

SDK を使用しない場合は predictLongRunning を呼び出せます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

curl -s \
  "https://generativelanguage.googleapis.com/v1beta/models/veo-3.1-generate-preview:predictLongRunning" \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "instances": [{
      "prompt": "A calm ocean at sunrise, slow aerial shot, natural waves"
    }],
    "parameters": {
      "aspectRatio": "16:9",
      "resolution": "720p",
      "durationSeconds": 4,
      "sampleCount": 1
    }
  }'

応答内の name は、後続のクエリに使用されます。 URL クエリ パラメーターやフロントエンド JavaScript に API キーを入力しないでください。

ポーリング REST 操作 

1
2
3

curl -s \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  "https://generativelanguage.googleapis.com/v1beta/${OPERATION_NAME}"

done が false になったら待ち続けます。 done が true になった後、response か error かを確認します。 完了したからといって成功が保証されるとは考えないでください。 「ビルドに失敗しました」だけが表示されるのを避けるために、完全なエラー構造とリクエスト ID を保存します。

ダウンロード URL には引き続き API キー

が必要です 完了応答は、生成されたビデオ URI を示します。 -L を使用してリダイレクトをたどります:

1
2
3
4

curl -L \
  -H "x-goog-api-key: ${GEMINI_API_KEY}" \
  -o veo-result.mp4 \
  "${VIDEO_URI}"

ダウンロード後にファイルの種類と期間を確認してください:

1
2
3

ffprobe -v error \
  -show_entries format=duration,size \
  -of json veo-result.mp4

ファイル拡張子を使用してダウンロードが成功したかどうかを判断するだけでなく、間違った JSON が .mp4 として保存される可能性もあります。

ビルドタスクに冪等キー

を設定する クライアントがタイムアウトになった後、すぐに同じプロンプトを再送信しないでください。 まず、ジョブ テーブルにすでにオペレーションがあるかどうかを確認します。 ユーザー ID、マテリアル ハッシュ、パラメータ、ビジネス リクエスト ID を使用して冪等キーを生成します。 同じキーに対して作成できるアップストリーム操作は 1 つだけです。 これにより、1 回のクリックで 2 つの課金対象ビデオが生成されることがなくなります。

コスト管理は2段階生成から始まります

最初のステージでは、高速、720p、および 4 秒を使用してプロンプトをスクリーニングしました。 第 2 段階では、選択したコンポジションのみを 8 秒、1080p または 4K にアップスケールします。 モデル、解像度、継続時間、操作、および最終的なファイル サイズを記録します。 単一の API 単価だけでなく、成功した本番環境に基づいてコストを計算します。 コンテンツモデレーションの失敗、パラメータの失敗、ユーザーのキャンセルも予算に考慮されます。

共通パラメータエラー

4 秒の 4K は継続時間要件に違反します。 1080p の拡張ビデオ リクエストは、拡張解像度の制限に違反します。 3 枚を超える参照画像は拒否されます。 最初と最後のフレームは最後のフレームのみを提供し、最初のフレームなしでは補間を形成できません。 プレビュー モデル ID の有効期限が切れると、モデルが存在しないことが返されます。 文字生成の制限は、地域や入力モードによっても異なる場合があります。

401、403、および 429 は個別に処理されます

401 は、まずキーが現在のプロセスに入ったかどうかを確認します。 403 プロジェクトの権限、リージョン、モデルのアクセス、および組織のポリシーをチェックします。 429 1 分あたりのリクエスト数、同時実行数、プロジェクト クォータをチェックします。 403 無限バックオフでは再試行しないでください。 クォータ エラーはキューに入れるか、ユーザーに後で再試行するよう求めるメッセージを表示する必要があります。

をダウンロードした後にメディア品質チェックを実行します コンテナのフォーマット、継続時間、解像度、フレームレート、オーディオトラックを確認します。

1
2
3
4

ffprobe -v error \
  -show_streams \
  -show_format \
  -of json veo-result.mp4 > veo-result.json

次に、最初のフレーム、中間フレーム、最後のフレームを抽出します:

1
2
3

ffmpeg -i veo-result.mp4 \
  -vf "select='eq(n,0)+eq(n,96)+eq(n,191)'" \
  -vsync 0 frame-%02d.png

フレーム番号は、実際の継続時間と fps に応じて調整する必要があります。

セキュリティとコンテンツの権利をパラメータに任せることはできません

人物、ブランド、製品の画像をアップロードする前に、使用権を確認してください。 欺瞞、嫌がらせ、なりすましを目的とした素材を生成しないでください。 元の画像、プロンプト、生成されたビデオには個人情報が含まれる場合があります。 一時ファイルの保存期間を設定し、base64 のイメージをログに保存しないでください。 ユーザー向け製品には、コンテンツの管理、レポート、削除パスも必要です。 生成されたすべての画像とビデオは、プラットフォームのウォーターマークとポリシーの対象となります。

オンラインになる前にタスクを承認

  • 操作名は永続化できます。
  • ワーカーは再起動後もポーリングを続行できます。
  • ダウンロードはリダイレクトに従い、認証が行われます。
  • 720p、1080p、および 4K パラメータの組み合わせは個別にテストされました。
  • 最初と最後のフレームと参照ピクチャの数が制限を満たしています。
  • 繰り返しのリクエストには再度請求されません。
  • ffprobe はオーディオとビデオのストリームを確認できます。
  • The failed task retains the error structure without saving the key.
  • ユーザーはマテリアルと生成された結果を削除できます。

Veo 3.1 API のエンジニアリング上の困難は、主に非同期タスク、パラメータ マトリックス、結果管理にあります。 First run through the 4-second 720p process, and then add the first and last frames, reference images, and 4K. It will be easier to locate the problem than submitting all advanced parameters at once.

公式情報