0
# Videos
1

2
Generate and manage videos using video generation models. Create videos from text prompts, retrieve video status, and manage video files.
3

4
## Capabilities
5

6
### Create Video
7

8
Generate a video from a text prompt.
9

10
```python { .api }
11
def create(
12
    self,
13
    *,
14
    prompt: str,
15
    input_reference: FileTypes | Omit = omit,
16
    model: VideoModel | Omit = omit,
17
    seconds: VideoSeconds | Omit = omit,
18
    size: VideoSize | Omit = omit,
19
    extra_headers: dict[str, str] | None = None,
20
    extra_query: dict[str, object] | None = None,
21
    extra_body: dict[str, object] | None = None,
22
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
23
) -> Video:
24
    """
25
    Create a video generation request.
26

27
    Args:
28
        prompt: Text description of the desired video.
29
        input_reference: Optional image reference that guides generation (FileTypes).
30
        model: Video model to use (e.g., "sora-2"). Defaults to "sora-2".
31
        seconds: Clip duration in seconds. Defaults to 4 seconds.
32
        size: Output resolution formatted as width x height (e.g., "720x1280").
33
            Defaults to "720x1280".
34
        extra_headers: Additional HTTP headers.
35
        extra_query: Additional query parameters.
36
        extra_body: Additional JSON fields.
37
        timeout: Request timeout in seconds.
38

39
    Returns:
40
        Video: Created video object with initial status.
41
    """
42
```
43

44
### Retrieve Video
45

46
Get video status and details.
47

48
```python { .api }
49
def retrieve(
50
    self,
51
    video_id: str,
52
    *,
53
    extra_headers: dict[str, str] | None = None,
54
    extra_query: dict[str, object] | None = None,
55
    extra_body: dict[str, object] | None = None,
56
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
57
) -> Video:
58
    """Retrieve video details and status."""
59
```
60

61
### Poll for Completion
62

63
Poll a video until it finishes processing (either completed or failed status).
64

65
```python { .api }
66
def poll(
67
    self,
68
    video_id: str,
69
    *,
70
    poll_interval_ms: int | Omit = omit,
71
) -> Video:
72
    """
73
    Wait for a video to finish processing.
74

75
    This method blocks until the video reaches "completed" or "failed" status.
76
    It automatically retries with appropriate polling intervals.
77

78
    Args:
79
        video_id: The ID of the video to poll.
80
        poll_interval_ms: Custom polling interval in milliseconds. If not provided,
81
            uses server-suggested interval or defaults to 1000ms.
82

83
    Returns:
84
        Video: The video object with final status ("completed" or "failed").
85

86
    Note:
87
        This method returns even if the video failed to process. Check
88
        video.status and video.error to handle failed cases.
89
    """
90
```
91

92
### List Videos
93

94
List all videos with pagination.
95

96
```python { .api }
97
def list(
98
    self,
99
    *,
100
    after: str | Omit = omit,
101
    limit: int | Omit = omit,
102
    order: Literal["asc", "desc"] | Omit = omit,
103
    extra_headers: dict[str, str] | None = None,
104
    extra_query: dict[str, object] | None = None,
105
    extra_body: dict[str, object] | None = None,
106
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
107
) -> SyncConversationCursorPage[Video]:
108
    """
109
    List videos with pagination.
110

111
    Args:
112
        after: Identifier for the last item from the previous pagination request.
113
        limit: Number of items to retrieve.
114
        order: Sort order by timestamp ("asc" or "desc").
115
        extra_headers: Additional HTTP headers.
116
        extra_query: Additional query parameters.
117
        extra_body: Additional JSON fields.
118
        timeout: Request timeout in seconds.
119

120
    Returns:
121
        SyncConversationCursorPage[Video]: Paginated list of videos.
122
    """
123
```
124

125
### Delete Video
126

127
Delete a video.
128

129
```python { .api }
130
def delete(
131
    self,
132
    video_id: str,
133
    *,
134
    extra_headers: dict[str, str] | None = None,
135
    extra_query: dict[str, object] | None = None,
136
    extra_body: dict[str, object] | None = None,
137
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
138
) -> VideoDeleteResponse:
139
    """Delete a video."""
140
```
141

142
### Download Video Content
143

144
Download the generated video file.
145

146
```python { .api }
147
def download_content(
148
    self,
149
    video_id: str,
150
    *,
151
    variant: Literal["video", "thumbnail", "spritesheet"] | Omit = omit,
152
    extra_headers: dict[str, str] | None = None,
153
    extra_query: dict[str, object] | None = None,
154
    extra_body: dict[str, object] | None = None,
155
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
156
) -> HttpxBinaryResponseContent:
157
    """
158
    Download video content as binary data.
159

160
    Args:
161
        video_id: The ID of the video to download.
162
        variant: The type of content to download. Options:
163
            - "video": The full video file (default)
164
            - "thumbnail": A thumbnail image of the video
165
            - "spritesheet": A spritesheet of video frames
166

167
    Returns:
168
        HttpxBinaryResponseContent: Binary video file content.
169
    """
170
```
171

172
### Remix Video
173

174
Create a new video by remixing an existing video with a new prompt.
175

176
```python { .api }
177
def remix(
178
    self,
179
    video_id: str,
180
    *,
181
    prompt: str,
182
    extra_headers: dict[str, str] | None = None,
183
    extra_query: dict[str, object] | None = None,
184
    extra_body: dict[str, object] | None = None,
185
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
186
) -> Video:
187
    """
188
    Create a remix of an existing video with a new prompt.
189

190
    Remixing uses the original video's model, duration, and size settings.
191
    Only the prompt can be changed to create variations.
192

193
    Args:
194
        video_id: The ID of the video to remix.
195
        prompt: New creative prompt to guide the remix.
196

197
    Returns:
198
        Video: Remix video object (status "queued" initially).
199
    """
200
```
201

202
Usage example:
203

204
```python
205
from openai import OpenAI
206

207
client = OpenAI()
208

209
# Create initial video
210
video = client.videos.create_and_poll(
211
    prompt="A serene sunset over mountains"
212
)
213

214
# Download the generated video
215
content = client.videos.download_content(video.id)
216
with open("sunset.mp4", "wb") as f:
217
    f.write(content.content)
218

219
# Create a remix with different prompt
220
remix = client.videos.remix(
221
    video.id,
222
    prompt="Transform the sunset to a dramatic thunderstorm"
223
)
224

225
# Poll for remix completion
226
while remix.status != "completed":
227
    time.sleep(5)
228
    remix = client.videos.retrieve(remix.id)
229

230
# Download remix
231
remix_content = client.videos.download_content(remix.id)
232
with open("storm.mp4", "wb") as f:
233
    f.write(remix_content.content)
234
```
235

236
### Create and Poll
237

238
Create video and wait for completion.
239

240
```python { .api }
241
def create_and_poll(
242
    self,
243
    *,
244
    prompt: str,
245
    input_reference: FileTypes | Omit = omit,
246
    model: VideoModel | Omit = omit,
247
    seconds: VideoSeconds | Omit = omit,
248
    size: VideoSize | Omit = omit,
249
    poll_interval_ms: int | Omit = omit,
250
    extra_headers: dict[str, str] | None = None,
251
    extra_query: dict[str, object] | None = None,
252
    extra_body: dict[str, object] | None = None,
253
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
254
) -> Video:
255
    """
256
    Create video and poll until generation completes.
257

258
    Args:
259
        prompt: Text description of the desired video.
260
        input_reference: Optional image reference that guides generation.
261
        model: Video model to use. Defaults to "sora-2".
262
        seconds: Clip duration in seconds.
263
        size: Output resolution.
264
        poll_interval_ms: Polling interval in milliseconds.
265
        extra_headers: Additional HTTP headers.
266
        extra_query: Additional query parameters.
267
        extra_body: Additional JSON fields.
268
        timeout: Request timeout in seconds.
269

270
    Returns:
271
        Video: Completed video object.
272
    """
273
```
274

275
Usage examples:
276

277
```python
278
from openai import OpenAI
279

280
client = OpenAI()
281

282
# Create video
283
video = client.videos.create(
284
    prompt="A serene mountain landscape at sunset",
285
    model="sora-2",
286
    seconds=5,
287
    size="720x1280"
288
)
289

290
print(f"Video ID: {video.id}")
291
print(f"Status: {video.status}")
292

293
# Create and wait for completion
294
video = client.videos.create_and_poll(
295
    prompt="Waves crashing on a beach",
296
    model="sora-2"
297
)
298

299
print(f"Final status: {video.status}")
300
if video.status == "completed" and video.url:
301
    print(f"Video URL: {video.url}")
302

303
# Check status
304
video = client.videos.retrieve("video_abc123")
305

306
# List videos
307
videos = client.videos.list(limit=10)
308

309
for video in videos.data:
310
    print(f"{video.id}: {video.status}")
311

312
# Delete video
313
result = client.videos.delete("video_abc123")
314
print(f"Deleted: {result.deleted}")
315
```
316

317
## Types
318

319
```python { .api }
320
from typing import Literal
321
from pydantic import BaseModel
322

323
class Video(BaseModel):
324
    """Video object."""
325
    id: str
326
    created_at: int
327
    model: str
328
    prompt: str
329
    status: Literal["queued", "processing", "completed", "failed"]
330
    url: str | None  # Available when completed
331
    error: dict | None  # Present if failed
332
    duration: int | None
333
    size: str | None
334

335
class VideoDeleteResponse(BaseModel):
336
    """Deletion confirmation."""
337
    id: str
338
    deleted: bool
339

340
VideoModel = Literal["sora-2", "sora-2-pro"]
341
```
342

343
## Async Usage
344

345
```python
346
import asyncio
347
from openai import AsyncOpenAI
348

349
async def create_video():
350
    client = AsyncOpenAI()
351

352
    video = await client.videos.create(
353
        model="video-gen-1",
354
        prompt="A futuristic city"
355
    )
356

357
    return video.id
358

359
video_id = asyncio.run(create_video())
360
```
361