ruby/resources/videos/methods/retrieve/index.md

Retrieve video

videos.retrieve(video_id) -> Video

get /videos/{video_id}

Fetch the latest metadata for a generated video.

Parameters

video_id: String

Returns

class Video

Structured information describing a generated video job.
- id: String
  
  Unique identifier for the video job.
- completed_at: Integer
  
  Unix timestamp (seconds) for when the job completed, if finished.
- created_at: Integer
  
  Unix timestamp (seconds) for when the job was created.
- error: VideoCreateError
  
  Error payload that explains why generation failed, if applicable.
  - code: String
    
    A machine-readable error code that was returned.
  - message: String
    
    A human-readable description of the error that was returned.
- expires_at: Integer
  
  Unix timestamp (seconds) for when the downloadable assets expire, if set.
- model: VideoModel
  
  The video generation model that produced the job.
  - String = String
  - VideoModel = :"sora-2" | :"sora-2-pro" | :"sora-2-2025-10-06" | 2 more
    - :"sora-2"
    - :"sora-2-pro"
    - :"sora-2-2025-10-06"
    - :"sora-2-pro-2025-10-06"
    - :"sora-2-2025-12-08"
- object: :video
  
  The object type, which is always video.
  - :video
- progress: Integer
  
  Approximate completion percentage for the generation task.
- prompt: String
  
  The prompt that was used to generate the video.
- remixed_from_video_id: String
  
  Identifier of the source video if this video is a remix.
- seconds: String | VideoSeconds
  
  Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
  - String = String
  - VideoSeconds = :"4" | :"8" | :"12"
    - :"4"
    - :"8"
    - :"12"
- size: VideoSize
  
  The resolution of the generated video.
  - :"720x1280"
  - :"1280x720"
  - :"1024x1792"
  - :"1792x1024"
- status: :queued | :in_progress | :completed | :failed
  
  Current lifecycle status of the video job.
  - :queued
  - :in_progress
  - :completed
  - :failed

Example

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

video = openai.videos.retrieve("video_123")

puts(video)

Response

{
  "id": "id",
  "completed_at": 0,
  "created_at": 0,
  "error": {
    "code": "code",
    "message": "message"
  },
  "expires_at": 0,
  "model": "sora-2",
  "object": "video",
  "progress": 0,
  "prompt": "prompt",
  "remixed_from_video_id": "remixed_from_video_id",
  "seconds": "4",
  "size": "720x1280",
  "status": "queued"
}

Example

require "openai"

openai = OpenAI::Client.new

video = openai.videos.retrieve("video_123")

puts(video)

ruby/resources/videos/methods/retrieve/index.md +166 −0 created

1## Retrieve video

3`videos.retrieve(video_id) -> Video`

5**get** `/videos/{video_id}`

7Fetch the latest metadata for a generated video.

9### Parameters

11- `video_id: String`

13### Returns

15- `class Video`

17 Structured information describing a generated video job.

19 - `id: String`

21 Unique identifier for the video job.

23 - `completed_at: Integer`

25 Unix timestamp (seconds) for when the job completed, if finished.

27 - `created_at: Integer`

29 Unix timestamp (seconds) for when the job was created.

31 - `error: VideoCreateError`

33 Error payload that explains why generation failed, if applicable.

35 - `code: String`

37 A machine-readable error code that was returned.

39 - `message: String`

41 A human-readable description of the error that was returned.

43 - `expires_at: Integer`

45 Unix timestamp (seconds) for when the downloadable assets expire, if set.

47 - `model: VideoModel`

49 The video generation model that produced the job.

51 - `String = String`

53 - `VideoModel = :"sora-2" | :"sora-2-pro" | :"sora-2-2025-10-06" | 2 more`

55 - `:"sora-2"`

57 - `:"sora-2-pro"`

59 - `:"sora-2-2025-10-06"`

61 - `:"sora-2-pro-2025-10-06"`

63 - `:"sora-2-2025-12-08"`

65 - `object: :video`

67 The object type, which is always `video`.

69 - `:video`

71 - `progress: Integer`

73 Approximate completion percentage for the generation task.

75 - `prompt: String`

77 The prompt that was used to generate the video.

79 - `remixed_from_video_id: String`

81 Identifier of the source video if this video is a remix.

83 - `seconds: String | VideoSeconds`

85 Duration of the generated clip in seconds. For extensions, this is the stitched total duration.

87 - `String = String`

89 - `VideoSeconds = :"4" | :"8" | :"12"`

91 - `:"4"`

93 - `:"8"`

95 - `:"12"`

97 - `size: VideoSize`

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": "sora-2",

146 "object": "video",

147 "progress": 0,

148 "prompt": "prompt",

149 "remixed_from_video_id": "remixed_from_video_id",

150 "seconds": "4",

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```

ruby/resources/videos/methods/retrieve/index.md 2026-06-10 15:48 UTC to 2026-06-12 00:01 UTC

Retrieve video

Parameters

Returns

Example

Response

Example