0
# Video Generation
1

2
Generate videos from text prompts, images, or existing videos using Veo models. Video generation is a long-running operation that returns immediately with an operation handle that can be polled for completion status.
3

4
## Capabilities
5

6
### Generate Videos
7

8
Generate videos from text prompts, optionally with reference images or videos. Returns a long-running operation that must be polled for completion.
9

10
```python { .api }
11
def generate_videos(
12
    *,
13
    model: str,
14
    prompt: Optional[str] = None,
15
    image: Optional[Image] = None,
16
    video: Optional[Video] = None,
17
    config: Optional[GenerateVideosConfig] = None
18
) -> GenerateVideosOperation:
19
    """
20
    Generate videos (returns long-running operation).
21

22
    Parameters:
23
        model (str): Model identifier (e.g., 'veo-2.0-generate-001', 'veo-001').
24
        prompt (str, optional): Text description of the video to generate. At least one
25
            of prompt, image, or video must be provided.
26
        image (Image, optional): Reference image for image-to-video generation.
27
        video (Video, optional): Reference video for video-to-video generation.
28
        config (GenerateVideosConfig, optional): Generation configuration including:
29
            - aspect_ratio: Video aspect ratio ('16:9', '9:16', '1:1')
30
            - duration: Video duration in seconds
31
            - negative_prompt: What to avoid
32
            - safety_filter_level: Safety filtering level
33
            - person_generation: Control person generation
34
            - compressed: Use compressed output format
35

36
    Returns:
37
        GenerateVideosOperation: Long-running operation handle. Use client.operations.get()
38
            to poll for completion and retrieve the generated videos.
39

40
    Raises:
41
        ClientError: For client errors (4xx status codes)
42
        ServerError: For server errors (5xx status codes)
43
    """
44
    ...
45

46
async def generate_videos(
47
    *,
48
    model: str,
49
    prompt: Optional[str] = None,
50
    image: Optional[Image] = None,
51
    video: Optional[Video] = None,
52
    config: Optional[GenerateVideosConfig] = None
53
) -> GenerateVideosOperation:
54
    """Async version of generate_videos."""
55
    ...
56
```
57

58
**Usage Example - Text to Video:**
59

60
```python
61
import time
62
from google.genai import Client
63
from google.genai.types import GenerateVideosConfig
64

65
client = Client(vertexai=True, project='PROJECT_ID', location='us-central1')
66

67
# Start video generation
68
config = GenerateVideosConfig(
69
    aspect_ratio='16:9',
70
    duration=5,  # 5 seconds
71
    negative_prompt='blurry, low quality'
72
)
73

74
operation = client.models.generate_videos(
75
    model='veo-2.0-generate-001',
76
    prompt='A dog running through a field of flowers at sunset',
77
    config=config
78
)
79

80
print(f"Operation started: {operation.name}")
81

82
# Poll for completion
83
while True:
84
    operation = client.operations.get(operation)
85

86
    if operation.done:
87
        if operation.error:
88
            print(f"Error: {operation.error}")
89
        else:
90
            response = operation.response
91
            print(f"Generated {len(response.generated_videos)} video(s)")
92

93
            # Save videos
94
            for i, video in enumerate(response.generated_videos):
95
                with open(f'generated_{i}.mp4', 'wb') as f:
96
                    f.write(video.video.data)
97
        break
98

99
    print("Still generating...")
100
    time.sleep(10)  # Wait 10 seconds before polling again
101
```
102

103
**Usage Example - Image to Video:**
104

105
```python
106
from google.genai import Client
107
from google.genai.types import Image, GenerateVideosConfig
108

109
client = Client(vertexai=True, project='PROJECT_ID', location='us-central1')
110

111
# Load reference image
112
image = Image.from_file('landscape.jpg')
113

114
config = GenerateVideosConfig(
115
    aspect_ratio='16:9',
116
    duration=8
117
)
118

119
# Generate video from image
120
operation = client.models.generate_videos(
121
    model='veo-2.0-generate-001',
122
    prompt='Camera slowly pans across the landscape',
123
    image=image,
124
    config=config
125
)
126

127
print(f"Operation: {operation.name}")
128
# Poll operation.done until complete
129
```
130

131
**Usage Example - Async with Polling:**
132

133
```python
134
import asyncio
135
from google.genai import Client
136

137
async def generate_and_wait():
138
    client = Client(vertexai=True, project='PROJECT_ID', location='us-central1')
139

140
    # Start generation
141
    operation = await client.aio.models.generate_videos(
142
        model='veo-2.0-generate-001',
143
        prompt='A cat playing with a ball of yarn'
144
    )
145

146
    print(f"Started operation: {operation.name}")
147

148
    # Poll until complete
149
    while not operation.done:
150
        await asyncio.sleep(10)
151
        operation = await client.aio.operations.get(operation)
152
        print("Checking status...")
153

154
    if operation.error:
155
        print(f"Error: {operation.error}")
156
    else:
157
        print(f"Success! {len(operation.response.generated_videos)} videos generated")
158

159
asyncio.run(generate_and_wait())
160
```
161

162
## Types
163

164
```python { .api }
165
from typing import Optional, Literal, TypedDict
166
from enum import Enum
167

168
# Configuration types
169
class GenerateVideosConfig:
170
    """
171
    Configuration for video generation.
172

173
    Attributes:
174
        aspect_ratio (str, optional): Video aspect ratio. Options: '16:9', '9:16', '1:1'.
175
            Default varies by model.
176
        duration (int, optional): Video duration in seconds. Valid range depends on model.
177
            Typical: 4-8 seconds.
178
        negative_prompt (str, optional): What to avoid in the video.
179
        safety_filter_level (str, optional): Safety filtering level ('block_most', 'block_some', 'block_few').
180
        person_generation (PersonGeneration, optional): Control person generation in video.
181
        compressed (bool, optional): Use compressed output format for smaller file size.
182
        generation_mode (str, optional): Generation mode (e.g., 'fast', 'quality').
183
    """
184
    aspect_ratio: Optional[str] = None
185
    duration: Optional[int] = None
186
    negative_prompt: Optional[str] = None
187
    safety_filter_level: Optional[str] = None
188
    person_generation: Optional[PersonGeneration] = None
189
    compressed: Optional[bool] = None
190
    generation_mode: Optional[str] = None
191

192
# Response types
193
class GenerateVideosResponse:
194
    """
195
    Response from completed video generation.
196

197
    Accessed via operation.response after operation completes.
198

199
    Attributes:
200
        generated_videos (list[GeneratedVideo]): Generated videos with metadata.
201
        rai_media_filtered_count (int, optional): Number of videos filtered by safety.
202
        rai_media_filtered_reasons (list[str], optional): Safety filtering reasons.
203
    """
204
    generated_videos: list[GeneratedVideo]
205
    rai_media_filtered_count: Optional[int] = None
206
    rai_media_filtered_reasons: Optional[list[str]] = None
207

208
class GeneratedVideo:
209
    """
210
    Generated video with metadata.
211

212
    Attributes:
213
        video (Video): Video object with data.
214
        generation_seed (int, optional): Seed used for generation (for reproducibility).
215
    """
216
    video: Video
217
    generation_seed: Optional[int] = None
218

219
# Operation types
220
class GenerateVideosOperation:
221
    """
222
    Long-running operation for video generation.
223

224
    Attributes:
225
        name (str): Operation name/identifier for polling.
226
        done (bool): Whether operation is complete.
227
        error (OperationError, optional): Error if operation failed.
228
        response (GenerateVideosResponse, optional): Response if operation succeeded.
229
        metadata (dict, optional): Operation metadata including progress.
230
    """
231
    name: str
232
    done: bool
233
    error: Optional[OperationError] = None
234
    response: Optional[GenerateVideosResponse] = None
235
    metadata: Optional[dict] = None
236

237
class OperationError:
238
    """
239
    Operation error information.
240

241
    Attributes:
242
        code (int): Error code.
243
        message (str): Error message.
244
        details (list, optional): Additional error details.
245
    """
246
    code: int
247
    message: str
248
    details: Optional[list] = None
249

250
# Input types
251
class Video:
252
    """
253
    Video data supporting multiple formats.
254

255
    Can be created from:
256
        - File: Video.from_file('path.mp4')
257
        - URL: Video.from_url('https://...')
258
        - Bytes: Video.from_bytes(data, mime_type='video/mp4')
259
        - FileData: Video(file_data=FileData(...))
260

261
    Attributes:
262
        data (bytes, optional): Video binary data.
263
        mime_type (str, optional): MIME type (e.g., 'video/mp4').
264
        file_data (FileData, optional): Reference to uploaded file.
265
    """
266
    data: Optional[bytes] = None
267
    mime_type: Optional[str] = None
268
    file_data: Optional[FileData] = None
269

270
    @staticmethod
271
    def from_file(path: str) -> Video:
272
        """Load video from file path."""
273
        ...
274

275
    @staticmethod
276
    def from_url(url: str) -> Video:
277
        """Load video from URL."""
278
        ...
279

280
    @staticmethod
281
    def from_bytes(data: bytes, mime_type: str) -> Video:
282
        """Create video from bytes."""
283
        ...
284

285
class Image:
286
    """Image data for image-to-video generation."""
287
    @staticmethod
288
    def from_file(path: str) -> Image: ...
289

290
class FileData:
291
    """
292
    Reference to uploaded file.
293

294
    Attributes:
295
        file_uri (str): URI (e.g., 'gs://bucket/file')
296
        mime_type (str): MIME type
297
    """
298
    file_uri: str
299
    mime_type: str
300

301
# Enum types
302
class PersonGeneration(Enum):
303
    """Person generation control."""
304
    DONT_ALLOW = 'dont_allow'
305
    ALLOW_ADULT = 'allow_adult'
306
    ALLOW_ALL = 'allow_all'
307

308
# TypedDict variants
309
class GenerateVideosConfigDict(TypedDict, total=False):
310
    """TypedDict variant of GenerateVideosConfig."""
311
    aspect_ratio: str
312
    duration: int
313
    negative_prompt: str
314
    safety_filter_level: str
315
    person_generation: PersonGeneration
316
    compressed: bool
317
    generation_mode: str
318
```
319