python/resources/videos/methods/retrieve/index.md +0 −169 deleted
File Deleted View Diff
1## Retrieve video
2
3`videos.retrieve(strvideo_id) -> Video`
4
5**get** `/videos/{video_id}`
6
7Fetch the latest metadata for a generated video.
8
9### Parameters
10
11- `video_id: str`
12
13### Returns
14
15- `class Video: …`
16
17 Structured information describing a generated video job.
18
19 - `id: str`
20
21 Unique identifier for the video job.
22
23 - `completed_at: Optional[int]`
24
25 Unix timestamp (seconds) for when the job completed, if finished.
26
27 - `created_at: int`
28
29 Unix timestamp (seconds) for when the job was created.
30
31 - `error: Optional[VideoCreateError]`
32
33 Error payload that explains why generation failed, if applicable.
34
35 - `code: str`
36
37 A machine-readable error code that was returned.
38
39 - `message: str`
40
41 A human-readable description of the error that was returned.
42
43 - `expires_at: Optional[int]`
44
45 Unix timestamp (seconds) for when the downloadable assets expire, if set.
46
47 - `model: VideoModel`
48
49 The video generation model that produced the job.
50
51 - `str`
52
53 - `Literal["sora-2", "sora-2-pro", "sora-2-2025-10-06", 2 more]`
54
55 - `"sora-2"`
56
57 - `"sora-2-pro"`
58
59 - `"sora-2-2025-10-06"`
60
61 - `"sora-2-pro-2025-10-06"`
62
63 - `"sora-2-2025-12-08"`
64
65 - `object: Literal["video"]`
66
67 The object type, which is always `video`.
68
69 - `"video"`
70
71 - `progress: int`
72
73 Approximate completion percentage for the generation task.
74
75 - `prompt: Optional[str]`
76
77 The prompt that was used to generate the video.
78
79 - `remixed_from_video_id: Optional[str]`
80
81 Identifier of the source video if this video is a remix.
82
83 - `seconds: Union[str, VideoSeconds]`
84
85 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
86
87 - `str`
88
89 - `Literal["4", "8", "12"]`
90
91 - `"4"`
92
93 - `"8"`
94
95 - `"12"`
96
97 - `size: VideoSize`
98
99 The resolution of the generated video.
100
101 - `"720x1280"`
102
103 - `"1280x720"`
104
105 - `"1024x1792"`
106
107 - `"1792x1024"`
108
109 - `status: Literal["queued", "in_progress", "completed", "failed"]`
110
111 Current lifecycle status of the video job.
112
113 - `"queued"`
114
115 - `"in_progress"`
116
117 - `"completed"`
118
119 - `"failed"`
120
121### Example
122
123```python
124import os
125from openai import OpenAI
126
127client = OpenAI(
128 api_key=os.environ.get("OPENAI_API_KEY"), # This is the default and can be omitted
129)
130video = client.videos.retrieve(
131 "video_123",
132)
133print(video.id)
134```
135
136#### Response
137
138```json
139{
140 "id": "id",
141 "completed_at": 0,
142 "created_at": 0,
143 "error": {
144 "code": "code",
145 "message": "message"
146 },
147 "expires_at": 0,
148 "model": "string",
149 "object": "video",
150 "progress": 0,
151 "prompt": "prompt",
152 "remixed_from_video_id": "remixed_from_video_id",
153 "seconds": "string",
154 "size": "720x1280",
155 "status": "queued"
156}
157```
158
159### Example
160
161```python
162from openai import OpenAI
163
164client = OpenAI()
165video = client.videos.retrieve(
166 "video_123",
167)
168print(video.id)
169```