ruby/resources/videos/methods/retrieve/index.md +0 −166 deleted
File Deleted View Diff
1## Retrieve video
2
3`videos.retrieve(video_id) -> Video`
4
5**get** `/videos/{video_id}`
6
7Fetch the latest metadata for a generated video.
8
9### Parameters
10
11- `video_id: String`
12
13### Returns
14
15- `class Video`
16
17 Structured information describing a generated video job.
18
19 - `id: String`
20
21 Unique identifier for the video job.
22
23 - `completed_at: Integer`
24
25 Unix timestamp (seconds) for when the job completed, if finished.
26
27 - `created_at: Integer`
28
29 Unix timestamp (seconds) for when the job was created.
30
31 - `error: VideoCreateError`
32
33 Error payload that explains why generation failed, if applicable.
34
35 - `code: String`
36
37 A machine-readable error code that was returned.
38
39 - `message: String`
40
41 A human-readable description of the error that was returned.
42
43 - `expires_at: Integer`
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 - `String = String`
52
53 - `VideoModel = :"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: :video`
66
67 The object type, which is always `video`.
68
69 - `:video`
70
71 - `progress: Integer`
72
73 Approximate completion percentage for the generation task.
74
75 - `prompt: String`
76
77 The prompt that was used to generate the video.
78
79 - `remixed_from_video_id: String`
80
81 Identifier of the source video if this video is a remix.
82
83 - `seconds: String | VideoSeconds`
84
85 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
86
87 - `String = String`
88
89 - `VideoSeconds = :"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: :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```ruby
124require "openai"
125
126openai = OpenAI::Client.new(api_key: "My API Key")
127
128video = openai.videos.retrieve("video_123")
129
130puts(video)
131```
132
133#### Response
134
135```json
136{
137 "id": "id",
138 "completed_at": 0,
139 "created_at": 0,
140 "error": {
141 "code": "code",
142 "message": "message"
143 },
144 "expires_at": 0,
145 "model": "string",
146 "object": "video",
147 "progress": 0,
148 "prompt": "prompt",
149 "remixed_from_video_id": "remixed_from_video_id",
150 "seconds": "string",
151 "size": "720x1280",
152 "status": "queued"
153}
154```
155
156### Example
157
158```ruby
159require "openai"
160
161openai = OpenAI::Client.new
162
163video = openai.videos.retrieve("video_123")
164
165puts(video)
166```