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