python/resources/videos/index.md +0 −1645 deleted
File Deleted View Diff
1# Videos
2
3## Create video
4
5`videos.create(VideoCreateParams**kwargs) -> Video`
6
7**post** `/videos`
8
9Create a new video generation job from a prompt and optional reference assets.
10
11### Parameters
12
13- `prompt: str`
14
15 Text prompt that describes the video to generate.
16
17- `input_reference: Optional[InputReference]`
18
19 Optional reference asset upload or reference object that guides generation.
20
21 - `FileTypes`
22
23 Optional reference asset upload or reference object that guides generation.
24
25 - `class ImageInputReferenceParam: …`
26
27 - `file_id: Optional[str]`
28
29 - `image_url: Optional[str]`
30
31 A fully qualified URL or base64-encoded data URL.
32
33- `model: Optional[VideoModelParam]`
34
35 The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to `sora-2`.
36
37 - `str`
38
39 - `Literal["sora-2", "sora-2-pro", "sora-2-2025-10-06", 2 more]`
40
41 - `"sora-2"`
42
43 - `"sora-2-pro"`
44
45 - `"sora-2-2025-10-06"`
46
47 - `"sora-2-pro-2025-10-06"`
48
49 - `"sora-2-2025-12-08"`
50
51- `seconds: Optional[VideoSeconds]`
52
53 Clip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds.
54
55 - `"4"`
56
57 - `"8"`
58
59 - `"12"`
60
61- `size: Optional[VideoSize]`
62
63 Output resolution formatted as width x height (allowed values: 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280.
64
65 - `"720x1280"`
66
67 - `"1280x720"`
68
69 - `"1024x1792"`
70
71 - `"1792x1024"`
72
73### Returns
74
75- `class Video: …`
76
77 Structured information describing a generated video job.
78
79 - `id: str`
80
81 Unique identifier for the video job.
82
83 - `completed_at: Optional[int]`
84
85 Unix timestamp (seconds) for when the job completed, if finished.
86
87 - `created_at: int`
88
89 Unix timestamp (seconds) for when the job was created.
90
91 - `error: Optional[VideoCreateError]`
92
93 Error payload that explains why generation failed, if applicable.
94
95 - `code: str`
96
97 A machine-readable error code that was returned.
98
99 - `message: str`
100
101 A human-readable description of the error that was returned.
102
103 - `expires_at: Optional[int]`
104
105 Unix timestamp (seconds) for when the downloadable assets expire, if set.
106
107 - `model: VideoModel`
108
109 The video generation model that produced the job.
110
111 - `str`
112
113 - `Literal["sora-2", "sora-2-pro", "sora-2-2025-10-06", 2 more]`
114
115 - `"sora-2"`
116
117 - `"sora-2-pro"`
118
119 - `"sora-2-2025-10-06"`
120
121 - `"sora-2-pro-2025-10-06"`
122
123 - `"sora-2-2025-12-08"`
124
125 - `object: Literal["video"]`
126
127 The object type, which is always `video`.
128
129 - `"video"`
130
131 - `progress: int`
132
133 Approximate completion percentage for the generation task.
134
135 - `prompt: Optional[str]`
136
137 The prompt that was used to generate the video.
138
139 - `remixed_from_video_id: Optional[str]`
140
141 Identifier of the source video if this video is a remix.
142
143 - `seconds: Union[str, VideoSeconds]`
144
145 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
146
147 - `str`
148
149 - `Literal["4", "8", "12"]`
150
151 - `"4"`
152
153 - `"8"`
154
155 - `"12"`
156
157 - `size: VideoSize`
158
159 The resolution of the generated video.
160
161 - `"720x1280"`
162
163 - `"1280x720"`
164
165 - `"1024x1792"`
166
167 - `"1792x1024"`
168
169 - `status: Literal["queued", "in_progress", "completed", "failed"]`
170
171 Current lifecycle status of the video job.
172
173 - `"queued"`
174
175 - `"in_progress"`
176
177 - `"completed"`
178
179 - `"failed"`
180
181### Example
182
183```python
184import os
185from openai import OpenAI
186
187client = OpenAI(
188 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
189)
190video = client.videos.create(
191 prompt="x",
192)
193print(video.id)
194```
195
196#### Response
197
198```json
199{
200 "id": "id",
201 "completed_at": 0,
202 "created_at": 0,
203 "error": {
204 "code": "code",
205 "message": "message"
206 },
207 "expires_at": 0,
208 "model": "string",
209 "object": "video",
210 "progress": 0,
211 "prompt": "prompt",
212 "remixed_from_video_id": "remixed_from_video_id",
213 "seconds": "string",
214 "size": "720x1280",
215 "status": "queued"
216}
217```
218
219### Example
220
221```python
222from openai import OpenAI
223
224client = OpenAI()
225video = client.videos.create(
226 prompt="A calico cat playing a piano on stage",
227)
228print(video.id)
229```
230
231#### Response
232
233```json
234{
235 "id": "video_123",
236 "object": "video",
237 "model": "sora-2",
238 "status": "queued",
239 "progress": 0,
240 "created_at": 1712697600,
241 "size": "1024x1792",
242 "seconds": "8",
243 "quality": "standard"
244}
245```
246
247## Create a new video generation job by editing a source video or existing generated video.
248
249`videos.edit(VideoEditParams**kwargs) -> Video`
250
251**post** `/videos/edits`
252
253Create a new video generation job by editing a source video or existing generated video.
254
255### Parameters
256
257- `prompt: str`
258
259 Text prompt that describes how to edit the source video.
260
261- `video: Video`
262
263 Reference to the completed video to edit.
264
265 - `FileTypes`
266
267 Reference to the completed video to edit.
268
269 - `class VideoVideoReferenceInputParam: …`
270
271 Reference to the completed video.
272
273 - `id: str`
274
275 The identifier of the completed video.
276
277### Returns
278
279- `class Video: …`
280
281 Structured information describing a generated video job.
282
283 - `id: str`
284
285 Unique identifier for the video job.
286
287 - `completed_at: Optional[int]`
288
289 Unix timestamp (seconds) for when the job completed, if finished.
290
291 - `created_at: int`
292
293 Unix timestamp (seconds) for when the job was created.
294
295 - `error: Optional[VideoCreateError]`
296
297 Error payload that explains why generation failed, if applicable.
298
299 - `code: str`
300
301 A machine-readable error code that was returned.
302
303 - `message: str`
304
305 A human-readable description of the error that was returned.
306
307 - `expires_at: Optional[int]`
308
309 Unix timestamp (seconds) for when the downloadable assets expire, if set.
310
311 - `model: VideoModel`
312
313 The video generation model that produced the job.
314
315 - `str`
316
317 - `Literal["sora-2", "sora-2-pro", "sora-2-2025-10-06", 2 more]`
318
319 - `"sora-2"`
320
321 - `"sora-2-pro"`
322
323 - `"sora-2-2025-10-06"`
324
325 - `"sora-2-pro-2025-10-06"`
326
327 - `"sora-2-2025-12-08"`
328
329 - `object: Literal["video"]`
330
331 The object type, which is always `video`.
332
333 - `"video"`
334
335 - `progress: int`
336
337 Approximate completion percentage for the generation task.
338
339 - `prompt: Optional[str]`
340
341 The prompt that was used to generate the video.
342
343 - `remixed_from_video_id: Optional[str]`
344
345 Identifier of the source video if this video is a remix.
346
347 - `seconds: Union[str, VideoSeconds]`
348
349 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
350
351 - `str`
352
353 - `Literal["4", "8", "12"]`
354
355 - `"4"`
356
357 - `"8"`
358
359 - `"12"`
360
361 - `size: VideoSize`
362
363 The resolution of the generated video.
364
365 - `"720x1280"`
366
367 - `"1280x720"`
368
369 - `"1024x1792"`
370
371 - `"1792x1024"`
372
373 - `status: Literal["queued", "in_progress", "completed", "failed"]`
374
375 Current lifecycle status of the video job.
376
377 - `"queued"`
378
379 - `"in_progress"`
380
381 - `"completed"`
382
383 - `"failed"`
384
385### Example
386
387```python
388import os
389from openai import OpenAI
390
391client = OpenAI(
392 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
393)
394video = client.videos.edit(
395 prompt="x",
396 video=b"Example data",
397)
398print(video.id)
399```
400
401#### Response
402
403```json
404{
405 "id": "id",
406 "completed_at": 0,
407 "created_at": 0,
408 "error": {
409 "code": "code",
410 "message": "message"
411 },
412 "expires_at": 0,
413 "model": "string",
414 "object": "video",
415 "progress": 0,
416 "prompt": "prompt",
417 "remixed_from_video_id": "remixed_from_video_id",
418 "seconds": "string",
419 "size": "720x1280",
420 "status": "queued"
421}
422```
423
424## Create an extension of a completed video.
425
426`videos.extend(VideoExtendParams**kwargs) -> Video`
427
428**post** `/videos/extensions`
429
430Create an extension of a completed video.
431
432### Parameters
433
434- `prompt: str`
435
436 Updated text prompt that directs the extension generation.
437
438- `seconds: VideoSeconds`
439
440 Length of the newly generated extension segment in seconds (allowed values: 4, 8, 12, 16, 20).
441
442 - `"4"`
443
444 - `"8"`
445
446 - `"12"`
447
448- `video: Video`
449
450 Reference to the completed video to extend.
451
452 - `FileTypes`
453
454 Reference to the completed video to extend.
455
456 - `class VideoVideoReferenceInputParam: …`
457
458 Reference to the completed video.
459
460 - `id: str`
461
462 The identifier of the completed video.
463
464### Returns
465
466- `class Video: …`
467
468 Structured information describing a generated video job.
469
470 - `id: str`
471
472 Unique identifier for the video job.
473
474 - `completed_at: Optional[int]`
475
476 Unix timestamp (seconds) for when the job completed, if finished.
477
478 - `created_at: int`
479
480 Unix timestamp (seconds) for when the job was created.
481
482 - `error: Optional[VideoCreateError]`
483
484 Error payload that explains why generation failed, if applicable.
485
486 - `code: str`
487
488 A machine-readable error code that was returned.
489
490 - `message: str`
491
492 A human-readable description of the error that was returned.
493
494 - `expires_at: Optional[int]`
495
496 Unix timestamp (seconds) for when the downloadable assets expire, if set.
497
498 - `model: VideoModel`
499
500 The video generation model that produced the job.
501
502 - `str`
503
504 - `Literal["sora-2", "sora-2-pro", "sora-2-2025-10-06", 2 more]`
505
506 - `"sora-2"`
507
508 - `"sora-2-pro"`
509
510 - `"sora-2-2025-10-06"`
511
512 - `"sora-2-pro-2025-10-06"`
513
514 - `"sora-2-2025-12-08"`
515
516 - `object: Literal["video"]`
517
518 The object type, which is always `video`.
519
520 - `"video"`
521
522 - `progress: int`
523
524 Approximate completion percentage for the generation task.
525
526 - `prompt: Optional[str]`
527
528 The prompt that was used to generate the video.
529
530 - `remixed_from_video_id: Optional[str]`
531
532 Identifier of the source video if this video is a remix.
533
534 - `seconds: Union[str, VideoSeconds]`
535
536 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
537
538 - `str`
539
540 - `Literal["4", "8", "12"]`
541
542 - `"4"`
543
544 - `"8"`
545
546 - `"12"`
547
548 - `size: VideoSize`
549
550 The resolution of the generated video.
551
552 - `"720x1280"`
553
554 - `"1280x720"`
555
556 - `"1024x1792"`
557
558 - `"1792x1024"`
559
560 - `status: Literal["queued", "in_progress", "completed", "failed"]`
561
562 Current lifecycle status of the video job.
563
564 - `"queued"`
565
566 - `"in_progress"`
567
568 - `"completed"`
569
570 - `"failed"`
571
572### Example
573
574```python
575import os
576from openai import OpenAI
577
578client = OpenAI(
579 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
580)
581video = client.videos.extend(
582 prompt="x",
583 seconds="4",
584 video=b"Example data",
585)
586print(video.id)
587```
588
589#### Response
590
591```json
592{
593 "id": "id",
594 "completed_at": 0,
595 "created_at": 0,
596 "error": {
597 "code": "code",
598 "message": "message"
599 },
600 "expires_at": 0,
601 "model": "string",
602 "object": "video",
603 "progress": 0,
604 "prompt": "prompt",
605 "remixed_from_video_id": "remixed_from_video_id",
606 "seconds": "string",
607 "size": "720x1280",
608 "status": "queued"
609}
610```
611
612## Create a character from an uploaded video.
613
614`videos.create_character(VideoCreateCharacterParams**kwargs) -> VideoCreateCharacterResponse`
615
616**post** `/videos/characters`
617
618Create a character from an uploaded video.
619
620### Parameters
621
622- `name: str`
623
624 Display name for this API character.
625
626- `video: FileTypes`
627
628 Video file used to create a character.
629
630### Returns
631
632- `class VideoCreateCharacterResponse: …`
633
634 - `id: Optional[str]`
635
636 Identifier for the character creation cameo.
637
638 - `created_at: int`
639
640 Unix timestamp (in seconds) when the character was created.
641
642 - `name: Optional[str]`
643
644 Display name for the character.
645
646### Example
647
648```python
649import os
650from openai import OpenAI
651
652client = OpenAI(
653 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
654)
655response = client.videos.create_character(
656 name="x",
657 video=b"Example data",
658)
659print(response.id)
660```
661
662#### Response
663
664```json
665{
666 "id": "id",
667 "created_at": 0,
668 "name": "name"
669}
670```
671
672## Fetch a character.
673
674`videos.get_character(strcharacter_id) -> VideoGetCharacterResponse`
675
676**get** `/videos/characters/{character_id}`
677
678Fetch a character.
679
680### Parameters
681
682- `character_id: str`
683
684### Returns
685
686- `class VideoGetCharacterResponse: …`
687
688 - `id: Optional[str]`
689
690 Identifier for the character creation cameo.
691
692 - `created_at: int`
693
694 Unix timestamp (in seconds) when the character was created.
695
696 - `name: Optional[str]`
697
698 Display name for the character.
699
700### Example
701
702```python
703import os
704from openai import OpenAI
705
706client = OpenAI(
707 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
708)
709response = client.videos.get_character(
710 "char_123",
711)
712print(response.id)
713```
714
715#### Response
716
717```json
718{
719 "id": "id",
720 "created_at": 0,
721 "name": "name"
722}
723```
724
725## List videos
726
727`videos.list(VideoListParams**kwargs) -> SyncConversationCursorPage[Video]`
728
729**get** `/videos`
730
731List recently generated videos for the current project.
732
733### Parameters
734
735- `after: Optional[str]`
736
737 Identifier for the last item from the previous pagination request
738
739- `limit: Optional[int]`
740
741 Number of items to retrieve
742
743- `order: Optional[Literal["asc", "desc"]]`
744
745 Sort order of results by timestamp. Use `asc` for ascending order or `desc` for descending order.
746
747 - `"asc"`
748
749 - `"desc"`
750
751### Returns
752
753- `class Video: …`
754
755 Structured information describing a generated video job.
756
757 - `id: str`
758
759 Unique identifier for the video job.
760
761 - `completed_at: Optional[int]`
762
763 Unix timestamp (seconds) for when the job completed, if finished.
764
765 - `created_at: int`
766
767 Unix timestamp (seconds) for when the job was created.
768
769 - `error: Optional[VideoCreateError]`
770
771 Error payload that explains why generation failed, if applicable.
772
773 - `code: str`
774
775 A machine-readable error code that was returned.
776
777 - `message: str`
778
779 A human-readable description of the error that was returned.
780
781 - `expires_at: Optional[int]`
782
783 Unix timestamp (seconds) for when the downloadable assets expire, if set.
784
785 - `model: VideoModel`
786
787 The video generation model that produced the job.
788
789 - `str`
790
791 - `Literal["sora-2", "sora-2-pro", "sora-2-2025-10-06", 2 more]`
792
793 - `"sora-2"`
794
795 - `"sora-2-pro"`
796
797 - `"sora-2-2025-10-06"`
798
799 - `"sora-2-pro-2025-10-06"`
800
801 - `"sora-2-2025-12-08"`
802
803 - `object: Literal["video"]`
804
805 The object type, which is always `video`.
806
807 - `"video"`
808
809 - `progress: int`
810
811 Approximate completion percentage for the generation task.
812
813 - `prompt: Optional[str]`
814
815 The prompt that was used to generate the video.
816
817 - `remixed_from_video_id: Optional[str]`
818
819 Identifier of the source video if this video is a remix.
820
821 - `seconds: Union[str, VideoSeconds]`
822
823 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
824
825 - `str`
826
827 - `Literal["4", "8", "12"]`
828
829 - `"4"`
830
831 - `"8"`
832
833 - `"12"`
834
835 - `size: VideoSize`
836
837 The resolution of the generated video.
838
839 - `"720x1280"`
840
841 - `"1280x720"`
842
843 - `"1024x1792"`
844
845 - `"1792x1024"`
846
847 - `status: Literal["queued", "in_progress", "completed", "failed"]`
848
849 Current lifecycle status of the video job.
850
851 - `"queued"`
852
853 - `"in_progress"`
854
855 - `"completed"`
856
857 - `"failed"`
858
859### Example
860
861```python
862import os
863from openai import OpenAI
864
865client = OpenAI(
866 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
867)
868page = client.videos.list()
869page = page.data[0]
870print(page.id)
871```
872
873#### Response
874
875```json
876{
877 "data": [
878 {
879 "id": "id",
880 "completed_at": 0,
881 "created_at": 0,
882 "error": {
883 "code": "code",
884 "message": "message"
885 },
886 "expires_at": 0,
887 "model": "string",
888 "object": "video",
889 "progress": 0,
890 "prompt": "prompt",
891 "remixed_from_video_id": "remixed_from_video_id",
892 "seconds": "string",
893 "size": "720x1280",
894 "status": "queued"
895 }
896 ],
897 "first_id": "first_id",
898 "has_more": true,
899 "last_id": "last_id",
900 "object": "list"
901}
902```
903
904### Example
905
906```python
907from openai import OpenAI
908
909client = OpenAI()
910page = client.videos.list()
911page = page.data[0]
912print(page.id)
913```
914
915#### Response
916
917```json
918{
919 "data": [
920 {
921 "id": "video_123",
922 "object": "video",
923 "model": "sora-2",
924 "status": "completed"
925 }
926 ],
927 "object": "list"
928}
929```
930
931## Retrieve video
932
933`videos.retrieve(strvideo_id) -> Video`
934
935**get** `/videos/{video_id}`
936
937Fetch the latest metadata for a generated video.
938
939### Parameters
940
941- `video_id: str`
942
943### Returns
944
945- `class Video: …`
946
947 Structured information describing a generated video job.
948
949 - `id: str`
950
951 Unique identifier for the video job.
952
953 - `completed_at: Optional[int]`
954
955 Unix timestamp (seconds) for when the job completed, if finished.
956
957 - `created_at: int`
958
959 Unix timestamp (seconds) for when the job was created.
960
961 - `error: Optional[VideoCreateError]`
962
963 Error payload that explains why generation failed, if applicable.
964
965 - `code: str`
966
967 A machine-readable error code that was returned.
968
969 - `message: str`
970
971 A human-readable description of the error that was returned.
972
973 - `expires_at: Optional[int]`
974
975 Unix timestamp (seconds) for when the downloadable assets expire, if set.
976
977 - `model: VideoModel`
978
979 The video generation model that produced the job.
980
981 - `str`
982
983 - `Literal["sora-2", "sora-2-pro", "sora-2-2025-10-06", 2 more]`
984
985 - `"sora-2"`
986
987 - `"sora-2-pro"`
988
989 - `"sora-2-2025-10-06"`
990
991 - `"sora-2-pro-2025-10-06"`
992
993 - `"sora-2-2025-12-08"`
994
995 - `object: Literal["video"]`
996
997 The object type, which is always `video`.
998
999 - `"video"`
1000
1001 - `progress: int`
1002
1003 Approximate completion percentage for the generation task.
1004
1005 - `prompt: Optional[str]`
1006
1007 The prompt that was used to generate the video.
1008
1009 - `remixed_from_video_id: Optional[str]`
1010
1011 Identifier of the source video if this video is a remix.
1012
1013 - `seconds: Union[str, VideoSeconds]`
1014
1015 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
1016
1017 - `str`
1018
1019 - `Literal["4", "8", "12"]`
1020
1021 - `"4"`
1022
1023 - `"8"`
1024
1025 - `"12"`
1026
1027 - `size: VideoSize`
1028
1029 The resolution of the generated video.
1030
1031 - `"720x1280"`
1032
1033 - `"1280x720"`
1034
1035 - `"1024x1792"`
1036
1037 - `"1792x1024"`
1038
1039 - `status: Literal["queued", "in_progress", "completed", "failed"]`
1040
1041 Current lifecycle status of the video job.
1042
1043 - `"queued"`
1044
1045 - `"in_progress"`
1046
1047 - `"completed"`
1048
1049 - `"failed"`
1050
1051### Example
1052
1053```python
1054import os
1055from openai import OpenAI
1056
1057client = OpenAI(
1058 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
1059)
1060video = client.videos.retrieve(
1061 "video_123",
1062)
1063print(video.id)
1064```
1065
1066#### Response
1067
1068```json
1069{
1070 "id": "id",
1071 "completed_at": 0,
1072 "created_at": 0,
1073 "error": {
1074 "code": "code",
1075 "message": "message"
1076 },
1077 "expires_at": 0,
1078 "model": "string",
1079 "object": "video",
1080 "progress": 0,
1081 "prompt": "prompt",
1082 "remixed_from_video_id": "remixed_from_video_id",
1083 "seconds": "string",
1084 "size": "720x1280",
1085 "status": "queued"
1086}
1087```
1088
1089### Example
1090
1091```python
1092from openai import OpenAI
1093
1094client = OpenAI()
1095video = client.videos.retrieve(
1096 "video_123",
1097)
1098print(video.id)
1099```
1100
1101## Delete video
1102
1103`videos.delete(strvideo_id) -> VideoDeleteResponse`
1104
1105**delete** `/videos/{video_id}`
1106
1107Permanently delete a completed or failed video and its stored assets.
1108
1109### Parameters
1110
1111- `video_id: str`
1112
1113### Returns
1114
1115- `class VideoDeleteResponse: …`
1116
1117 Confirmation payload returned after deleting a video.
1118
1119 - `id: str`
1120
1121 Identifier of the deleted video.
1122
1123 - `deleted: bool`
1124
1125 Indicates that the video resource was deleted.
1126
1127 - `object: Literal["video.deleted"]`
1128
1129 The object type that signals the deletion response.
1130
1131 - `"video.deleted"`
1132
1133### Example
1134
1135```python
1136import os
1137from openai import OpenAI
1138
1139client = OpenAI(
1140 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
1141)
1142video = client.videos.delete(
1143 "video_123",
1144)
1145print(video.id)
1146```
1147
1148#### Response
1149
1150```json
1151{
1152 "id": "id",
1153 "deleted": true,
1154 "object": "video.deleted"
1155}
1156```
1157
1158### Example
1159
1160```python
1161from openai import OpenAI
1162
1163client = OpenAI()
1164video = client.videos.delete(
1165 "video_123",
1166)
1167print(video.id)
1168```
1169
1170## Remix video
1171
1172`videos.remix(strvideo_id, VideoRemixParams**kwargs) -> Video`
1173
1174**post** `/videos/{video_id}/remix`
1175
1176Create a remix of a completed video using a refreshed prompt.
1177
1178### Parameters
1179
1180- `video_id: str`
1181
1182- `prompt: str`
1183
1184 Updated text prompt that directs the remix generation.
1185
1186### Returns
1187
1188- `class Video: …`
1189
1190 Structured information describing a generated video job.
1191
1192 - `id: str`
1193
1194 Unique identifier for the video job.
1195
1196 - `completed_at: Optional[int]`
1197
1198 Unix timestamp (seconds) for when the job completed, if finished.
1199
1200 - `created_at: int`
1201
1202 Unix timestamp (seconds) for when the job was created.
1203
1204 - `error: Optional[VideoCreateError]`
1205
1206 Error payload that explains why generation failed, if applicable.
1207
1208 - `code: str`
1209
1210 A machine-readable error code that was returned.
1211
1212 - `message: str`
1213
1214 A human-readable description of the error that was returned.
1215
1216 - `expires_at: Optional[int]`
1217
1218 Unix timestamp (seconds) for when the downloadable assets expire, if set.
1219
1220 - `model: VideoModel`
1221
1222 The video generation model that produced the job.
1223
1224 - `str`
1225
1226 - `Literal["sora-2", "sora-2-pro", "sora-2-2025-10-06", 2 more]`
1227
1228 - `"sora-2"`
1229
1230 - `"sora-2-pro"`
1231
1232 - `"sora-2-2025-10-06"`
1233
1234 - `"sora-2-pro-2025-10-06"`
1235
1236 - `"sora-2-2025-12-08"`
1237
1238 - `object: Literal["video"]`
1239
1240 The object type, which is always `video`.
1241
1242 - `"video"`
1243
1244 - `progress: int`
1245
1246 Approximate completion percentage for the generation task.
1247
1248 - `prompt: Optional[str]`
1249
1250 The prompt that was used to generate the video.
1251
1252 - `remixed_from_video_id: Optional[str]`
1253
1254 Identifier of the source video if this video is a remix.
1255
1256 - `seconds: Union[str, VideoSeconds]`
1257
1258 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
1259
1260 - `str`
1261
1262 - `Literal["4", "8", "12"]`
1263
1264 - `"4"`
1265
1266 - `"8"`
1267
1268 - `"12"`
1269
1270 - `size: VideoSize`
1271
1272 The resolution of the generated video.
1273
1274 - `"720x1280"`
1275
1276 - `"1280x720"`
1277
1278 - `"1024x1792"`
1279
1280 - `"1792x1024"`
1281
1282 - `status: Literal["queued", "in_progress", "completed", "failed"]`
1283
1284 Current lifecycle status of the video job.
1285
1286 - `"queued"`
1287
1288 - `"in_progress"`
1289
1290 - `"completed"`
1291
1292 - `"failed"`
1293
1294### Example
1295
1296```python
1297import os
1298from openai import OpenAI
1299
1300client = OpenAI(
1301 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
1302)
1303video = client.videos.remix(
1304 video_id="video_123",
1305 prompt="x",
1306)
1307print(video.id)
1308```
1309
1310#### Response
1311
1312```json
1313{
1314 "id": "id",
1315 "completed_at": 0,
1316 "created_at": 0,
1317 "error": {
1318 "code": "code",
1319 "message": "message"
1320 },
1321 "expires_at": 0,
1322 "model": "string",
1323 "object": "video",
1324 "progress": 0,
1325 "prompt": "prompt",
1326 "remixed_from_video_id": "remixed_from_video_id",
1327 "seconds": "string",
1328 "size": "720x1280",
1329 "status": "queued"
1330}
1331```
1332
1333### Example
1334
1335```python
1336from openai import OpenAI
1337
1338client = OpenAI()
1339video = client.videos.remix(
1340 video_id="video_123",
1341 prompt="Extend the scene with the cat taking a bow to the cheering audience",
1342)
1343print(video.id)
1344```
1345
1346#### Response
1347
1348```json
1349{
1350 "id": "video_456",
1351 "object": "video",
1352 "model": "sora-2",
1353 "status": "queued",
1354 "progress": 0,
1355 "created_at": 1712698600,
1356 "size": "720x1280",
1357 "seconds": "8",
1358 "remixed_from_video_id": "video_123"
1359}
1360```
1361
1362## Retrieve video content
1363
1364`videos.download_content(strvideo_id, VideoDownloadContentParams**kwargs) -> BinaryResponseContent`
1365
1366**get** `/videos/{video_id}/content`
1367
1368Download the generated video bytes or a derived preview asset.
1369
1370Streams the rendered video content for the specified video job.
1371
1372### Parameters
1373
1374- `video_id: str`
1375
1376- `variant: Optional[Literal["video", "thumbnail", "spritesheet"]]`
1377
1378 Which downloadable asset to return. Defaults to the MP4 video.
1379
1380 - `"video"`
1381
1382 - `"thumbnail"`
1383
1384 - `"spritesheet"`
1385
1386### Returns
1387
1388- `BinaryResponseContent`
1389
1390### Example
1391
1392```python
1393import os
1394from openai import OpenAI
1395
1396client = OpenAI(
1397 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
1398)
1399response = client.videos.download_content(
1400 video_id="video_123",
1401)
1402print(response)
1403content = response.read()
1404print(content)
1405```
1406
1407### Example
1408
1409```python
1410from openai import OpenAI
1411
1412client = OpenAI()
1413response = client.videos.download_content(
1414 video_id="video_123",
1415)
1416print(response)
1417content = response.read()
1418print(content)
1419```
1420
1421## Domain Types
1422
1423### Image Input Reference Param
1424
1425- `class ImageInputReferenceParam: …`
1426
1427 - `file_id: Optional[str]`
1428
1429 - `image_url: Optional[str]`
1430
1431 A fully qualified URL or base64-encoded data URL.
1432
1433### Video
1434
1435- `class Video: …`
1436
1437 Structured information describing a generated video job.
1438
1439 - `id: str`
1440
1441 Unique identifier for the video job.
1442
1443 - `completed_at: Optional[int]`
1444
1445 Unix timestamp (seconds) for when the job completed, if finished.
1446
1447 - `created_at: int`
1448
1449 Unix timestamp (seconds) for when the job was created.
1450
1451 - `error: Optional[VideoCreateError]`
1452
1453 Error payload that explains why generation failed, if applicable.
1454
1455 - `code: str`
1456
1457 A machine-readable error code that was returned.
1458
1459 - `message: str`
1460
1461 A human-readable description of the error that was returned.
1462
1463 - `expires_at: Optional[int]`
1464
1465 Unix timestamp (seconds) for when the downloadable assets expire, if set.
1466
1467 - `model: VideoModel`
1468
1469 The video generation model that produced the job.
1470
1471 - `str`
1472
1473 - `Literal["sora-2", "sora-2-pro", "sora-2-2025-10-06", 2 more]`
1474
1475 - `"sora-2"`
1476
1477 - `"sora-2-pro"`
1478
1479 - `"sora-2-2025-10-06"`
1480
1481 - `"sora-2-pro-2025-10-06"`
1482
1483 - `"sora-2-2025-12-08"`
1484
1485 - `object: Literal["video"]`
1486
1487 The object type, which is always `video`.
1488
1489 - `"video"`
1490
1491 - `progress: int`
1492
1493 Approximate completion percentage for the generation task.
1494
1495 - `prompt: Optional[str]`
1496
1497 The prompt that was used to generate the video.
1498
1499 - `remixed_from_video_id: Optional[str]`
1500
1501 Identifier of the source video if this video is a remix.
1502
1503 - `seconds: Union[str, VideoSeconds]`
1504
1505 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
1506
1507 - `str`
1508
1509 - `Literal["4", "8", "12"]`
1510
1511 - `"4"`
1512
1513 - `"8"`
1514
1515 - `"12"`
1516
1517 - `size: VideoSize`
1518
1519 The resolution of the generated video.
1520
1521 - `"720x1280"`
1522
1523 - `"1280x720"`
1524
1525 - `"1024x1792"`
1526
1527 - `"1792x1024"`
1528
1529 - `status: Literal["queued", "in_progress", "completed", "failed"]`
1530
1531 Current lifecycle status of the video job.
1532
1533 - `"queued"`
1534
1535 - `"in_progress"`
1536
1537 - `"completed"`
1538
1539 - `"failed"`
1540
1541### Video Create Error
1542
1543- `class VideoCreateError: …`
1544
1545 An error that occurred while generating the response.
1546
1547 - `code: str`
1548
1549 A machine-readable error code that was returned.
1550
1551 - `message: str`
1552
1553 A human-readable description of the error that was returned.
1554
1555### Video Model
1556
1557- `Union[str, Literal["sora-2", "sora-2-pro", "sora-2-2025-10-06", 2 more]]`
1558
1559 - `str`
1560
1561 - `Literal["sora-2", "sora-2-pro", "sora-2-2025-10-06", 2 more]`
1562
1563 - `"sora-2"`
1564
1565 - `"sora-2-pro"`
1566
1567 - `"sora-2-2025-10-06"`
1568
1569 - `"sora-2-pro-2025-10-06"`
1570
1571 - `"sora-2-2025-12-08"`
1572
1573### Video Seconds
1574
1575- `Literal["4", "8", "12"]`
1576
1577 - `"4"`
1578
1579 - `"8"`
1580
1581 - `"12"`
1582
1583### Video Size
1584
1585- `Literal["720x1280", "1280x720", "1024x1792", "1792x1024"]`
1586
1587 - `"720x1280"`
1588
1589 - `"1280x720"`
1590
1591 - `"1024x1792"`
1592
1593 - `"1792x1024"`
1594
1595### Video Create Character Response
1596
1597- `class VideoCreateCharacterResponse: …`
1598
1599 - `id: Optional[str]`
1600
1601 Identifier for the character creation cameo.
1602
1603 - `created_at: int`
1604
1605 Unix timestamp (in seconds) when the character was created.
1606
1607 - `name: Optional[str]`
1608
1609 Display name for the character.
1610
1611### Video Get Character Response
1612
1613- `class VideoGetCharacterResponse: …`
1614
1615 - `id: Optional[str]`
1616
1617 Identifier for the character creation cameo.
1618
1619 - `created_at: int`
1620
1621 Unix timestamp (in seconds) when the character was created.
1622
1623 - `name: Optional[str]`
1624
1625 Display name for the character.
1626
1627### Video Delete Response
1628
1629- `class VideoDeleteResponse: …`
1630
1631 Confirmation payload returned after deleting a video.
1632
1633 - `id: str`
1634
1635 Identifier of the deleted video.
1636
1637 - `deleted: bool`
1638
1639 Indicates that the video resource was deleted.
1640
1641 - `object: Literal["video.deleted"]`
1642
1643 The object type that signals the deletion response.
1644
1645 - `"video.deleted"`