File Deleted
View Diff
1> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.
2
3## Create a video
4
5**post** `/videos`
6
7Create a new video generation job from a prompt and optional reference assets.
8
9### Body Parameters
10
11- `prompt: string`
12
13 Text prompt that describes the video to generate.
14
15- `input_reference: optional ImageInputReferenceParam`
16
17 Optional reference object that guides generation. Provide exactly one of `image_url` or `file_id`.
18
19 - `file_id: optional string`
20
21 - `image_url: optional string`
22
23 A fully qualified URL or base64-encoded data URL.
24
25- `model: optional VideoModel`
26
27 The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to `sora-2`.
28
29 - `string`
30
31 - `"sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`
32
33 - `"sora-2"`
34
35 - `"sora-2-pro"`
36
37 - `"sora-2-2025-10-06"`
38
39 - `"sora-2-pro-2025-10-06"`
40
41 - `"sora-2-2025-12-08"`
42
43- `seconds: optional VideoSeconds`
44
45 Clip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds.
46
47 - `"4"`
48
49 - `"8"`
50
51 - `"12"`
52
53- `size: optional VideoSize`
54
55 Output resolution formatted as width x height (allowed values: 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280.
56
57 - `"720x1280"`
58
59 - `"1280x720"`
60
61 - `"1024x1792"`
62
63 - `"1792x1024"`
64
65### Returns
66
67- `Video object { id, completed_at, created_at, 10 more }`
68
69 Structured information describing a generated video job.
70
71 - `id: string`
72
73 Unique identifier for the video job.
74
75 - `completed_at: number or null`
76
77 Unix timestamp (seconds) for when the job completed, if finished.
78
79 - `created_at: number`
80
81 Unix timestamp (seconds) for when the job was created.
82
83 - `error: VideoCreateError or null`
84
85 Error payload that explains why generation failed, if applicable.
86
87 - `code: string`
88
89 A machine-readable error code that was returned.
90
91 - `message: string`
92
93 A human-readable description of the error that was returned.
94
95 - `headers: optional map[string]`
96
97 The Retry-After and Retry-After-Ms headers returned with the original error, if any.
98
99 - `misalignment: optional object { detailed_explanation, error_type, steer }`
100
101 - `detailed_explanation: optional string`
102
103 The public explanation for this block.
104
105 - `error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"`
106
107 An optional classification; clients must accept additional values.
108
109 - `string`
110
111 - `SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"`
112
113 An optional classification; clients must accept additional values.
114
115 - `"potentially_unintended_data_transfer"`
116
117 - `"potentially_unintended_data_access"`
118
119 - `"potentially_unintended_destructive_activity"`
120
121 - `"other"`
122
123 - `steer: optional object { message }`
124
125 An optional public continuation instruction.
126
127 - `message: string`
128
129 The public continuation instruction.
130
131 - `expires_at: number or null`
132
133 Unix timestamp (seconds) for when the downloadable assets expire, if set.
134
135 - `model: VideoModel`
136
137 The video generation model that produced the job.
138
139 - `string`
140
141 - `"sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`
142
143 - `"sora-2"`
144
145 - `"sora-2-pro"`
146
147 - `"sora-2-2025-10-06"`
148
149 - `"sora-2-pro-2025-10-06"`
150
151 - `"sora-2-2025-12-08"`
152
153 - `object: "video"`
154
155 The object type, which is always `video`.
156
157 - `"video"`
158
159 - `progress: number`
160
161 Approximate completion percentage for the generation task.
162
163 - `prompt: string or null`
164
165 The prompt that was used to generate the video.
166
167 - `remixed_from_video_id: string or null`
168
169 Identifier of the source video if this video is a remix.
170
171 - `seconds: string`
172
173 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
174
175 - `size: VideoSize`
176
177 The resolution of the generated video.
178
179 - `"720x1280"`
180
181 - `"1280x720"`
182
183 - `"1024x1792"`
184
185 - `"1792x1024"`
186
187 - `status: "queued" or "in_progress" or "completed" or "failed"`
188
189 Current lifecycle status of the video job.
190
191 - `"queued"`
192
193 - `"in_progress"`
194
195 - `"completed"`
196
197 - `"failed"`
198
199### Example
200
201```http
202curl https://api.openai.com/v1/videos \
203 -H 'Content-Type: application/json' \
204 -H "Authorization: Bearer $OPENAI_API_KEY" \
205 -d '{
206 "prompt": "x"
207 }'
208```
209
210#### Response
211
212```json
213{
214 "id": "id",
215 "completed_at": 0,
216 "created_at": 0,
217 "error": {
218 "code": "code",
219 "message": "message",
220 "headers": {
221 "foo": "string"
222 },
223 "misalignment": {
224 "detailed_explanation": "detailed_explanation",
225 "error_type": "potentially_unintended_data_transfer",
226 "steer": {
227 "message": "message"
228 }
229 }
230 },
231 "expires_at": 0,
232 "model": "sora-2",
233 "object": "video",
234 "progress": 0,
235 "prompt": "prompt",
236 "remixed_from_video_id": "remixed_from_video_id",
237 "seconds": "string",
238 "size": "720x1280",
239 "status": "queued"
240}
241```
242
243### Example
244
245```http
246curl https://api.openai.com/v1/videos \
247 -H "Authorization: Bearer $OPENAI_API_KEY" \
248 -F "model=sora-2" \
249 -F "prompt=A calico cat playing a piano on stage"
250```
251
252#### Response
253
254```json
255{
256 "id": "video_123",
257 "object": "video",
258 "model": "sora-2",
259 "status": "queued",
260 "progress": 0,
261 "created_at": 1712697600,
262 "size": "1024x1792",
263 "seconds": "8",
264 "quality": "standard"
265}
266```
