Veo 3.1 API 影片生成教學：首尾影格、參考圖、4K 與非同步輪詢

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

 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())

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"
}

 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,
    ),
)

 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,
    ),
)

1
2
3
4
5

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

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.

 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
    }
  }'

1
2
3

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

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

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