resources/videos/methods/list/index.md +0 −248 deleted
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## List videos
4
5**get** `/videos`
6
7List recently generated videos for the current project.
8
9### Query Parameters
10
11- `after: optional string`
12
13 Identifier for the last item from the previous pagination request
14
15- `limit: optional number`
16
17 Number of items to retrieve
18
19- `order: optional "asc" or "desc"`
20
21 Sort order of results by timestamp. Use `asc` for ascending order or `desc` for descending order.
22
23 - `"asc"`
24
25 - `"desc"`
26
27### Returns
28
29- `data: array of Video`
30
31 A list of items
32
33 - `id: string`
34
35 Unique identifier for the video job.
36
37 - `completed_at: number or null`
38
39 Unix timestamp (seconds) for when the job completed, if finished.
40
41 - `created_at: number`
42
43 Unix timestamp (seconds) for when the job was created.
44
45 - `error: VideoCreateError or null`
46
47 Error payload that explains why generation failed, if applicable.
48
49 - `code: string`
50
51 A machine-readable error code that was returned.
52
53 - `message: string`
54
55 A human-readable description of the error that was returned.
56
57 - `headers: optional map[string]`
58
59 The Retry-After and Retry-After-Ms headers returned with the original error, if any.
60
61 - `misalignment: optional object { detailed_explanation, error_type, steer }`
62
63 - `detailed_explanation: optional string`
64
65 The public explanation for this block.
66
67 - `error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"`
68
69 An optional classification; clients must accept additional values.
70
71 - `string`
72
73 - `SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"`
74
75 An optional classification; clients must accept additional values.
76
77 - `"potentially_unintended_data_transfer"`
78
79 - `"potentially_unintended_data_access"`
80
81 - `"potentially_unintended_destructive_activity"`
82
83 - `"other"`
84
85 - `steer: optional object { message }`
86
87 An optional public continuation instruction.
88
89 - `message: string`
90
91 The public continuation instruction.
92
93 - `expires_at: number or null`
94
95 Unix timestamp (seconds) for when the downloadable assets expire, if set.
96
97 - `model: VideoModel`
98
99 The video generation model that produced the job.
100
101 - `string`
102
103 - `"sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`
104
105 - `"sora-2"`
106
107 - `"sora-2-pro"`
108
109 - `"sora-2-2025-10-06"`
110
111 - `"sora-2-pro-2025-10-06"`
112
113 - `"sora-2-2025-12-08"`
114
115 - `object: "video"`
116
117 The object type, which is always `video`.
118
119 - `"video"`
120
121 - `progress: number`
122
123 Approximate completion percentage for the generation task.
124
125 - `prompt: string or null`
126
127 The prompt that was used to generate the video.
128
129 - `remixed_from_video_id: string or null`
130
131 Identifier of the source video if this video is a remix.
132
133 - `seconds: string`
134
135 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
136
137 - `size: VideoSize`
138
139 The resolution of the generated video.
140
141 - `"720x1280"`
142
143 - `"1280x720"`
144
145 - `"1024x1792"`
146
147 - `"1792x1024"`
148
149 - `status: "queued" or "in_progress" or "completed" or "failed"`
150
151 Current lifecycle status of the video job.
152
153 - `"queued"`
154
155 - `"in_progress"`
156
157 - `"completed"`
158
159 - `"failed"`
160
161- `first_id: string or null`
162
163 The ID of the first item in the list.
164
165- `has_more: boolean`
166
167 Whether there are more items available.
168
169- `last_id: string or null`
170
171 The ID of the last item in the list.
172
173- `object: "list"`
174
175 The type of object returned, must be `list`.
176
177 - `"list"`
178
179### Example
180
181```http
182curl https://api.openai.com/v1/videos \
183 -H "Authorization: Bearer $OPENAI_API_KEY"
184```
185
186#### Response
187
188```json
189{
190 "data": [
191 {
192 "id": "id",
193 "completed_at": 0,
194 "created_at": 0,
195 "error": {
196 "code": "code",
197 "message": "message",
198 "headers": {
199 "foo": "string"
200 },
201 "misalignment": {
202 "detailed_explanation": "detailed_explanation",
203 "error_type": "potentially_unintended_data_transfer",
204 "steer": {
205 "message": "message"
206 }
207 }
208 },
209 "expires_at": 0,
210 "model": "sora-2",
211 "object": "video",
212 "progress": 0,
213 "prompt": "prompt",
214 "remixed_from_video_id": "remixed_from_video_id",
215 "seconds": "string",
216 "size": "720x1280",
217 "status": "queued"
218 }
219 ],
220 "first_id": "first_id",
221 "has_more": true,
222 "last_id": "last_id",
223 "object": "list"
224}
225```
226
227### Example
228
229```http
230curl https://api.openai.com/v1/videos \
231 -H "Authorization: Bearer $OPENAI_API_KEY"
232```
233
234#### Response
235
236```json
237{
238 "data": [
239 {
240 "id": "video_123",
241 "object": "video",
242 "model": "sora-2",
243 "status": "completed"
244 }
245 ],
246 "object": "list"
247}
248```