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

Create video

videos.create(**kwargs) -> Video

post /videos

Create a new video generation job from a prompt and optional reference assets.

Parameters

prompt: String

Text prompt that describes the video to generate.
input_reference: String | ImageInputReferenceParam

Optional reference asset upload or reference object that guides generation.
- String = String
  
  Optional reference asset upload or reference object that guides generation.
- class ImageInputReferenceParam
  - file_id: String
  - image_url: String
    
    A fully qualified URL or base64-encoded data URL.
model: VideoModel

The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to sora-2.
- 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"
seconds: VideoSeconds

Clip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds.
- :"4"
- :"8"
- :"12"
size: VideoSize

Output resolution formatted as width x height (allowed values: 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280.
- :"720x1280"
- :"1280x720"
- :"1024x1792"
- :"1792x1024"

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.create(prompt: "x")

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.create(prompt: "A calico cat playing a piano on stage")

puts(video)

Response

{
  "id": "video_123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "size": "1024x1792",
  "seconds": "8",
  "quality": "standard"
}

ruby/resources/videos/methods/create/index.md +240 −0 created

1## Create video

3`videos.create(**kwargs) -> Video`

5**post** `/videos`

7Create a new video generation job from a prompt and optional reference assets.

9### Parameters

11- `prompt: String`

13 Text prompt that describes the video to generate.

15- `input_reference: String | ImageInputReferenceParam`

17 Optional reference asset upload or reference object that guides generation.

19 - `String = String`

21 Optional reference asset upload or reference object that guides generation.

23 - `class ImageInputReferenceParam`

25 - `file_id: String`

27 - `image_url: String`

29 A fully qualified URL or base64-encoded data URL.

31- `model: VideoModel`

33 The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to `sora-2`.

35 - `String = String`

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

39 - `:"sora-2"`

41 - `:"sora-2-pro"`

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

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

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

49- `seconds: VideoSeconds`

51 Clip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds.

53 - `:"4"`

55 - `:"8"`

57 - `:"12"`

59- `size: VideoSize`

61 Output resolution formatted as width x height (allowed values: 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280.

63 - `:"720x1280"`

65 - `:"1280x720"`

67 - `:"1024x1792"`

69 - `:"1792x1024"`

71### Returns

73- `class Video`

75 Structured information describing a generated video job.

77 - `id: String`

79 Unique identifier for the video job.

81 - `completed_at: Integer`

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

85 - `created_at: Integer`

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

89 - `error: VideoCreateError`

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

93 - `code: String`

95 A machine-readable error code that was returned.

97 - `message: String`

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

100

101 - `expires_at: Integer`

102

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

104

105 - `model: VideoModel`

106

107 The video generation model that produced the job.

108

109 - `String = String`

110

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

112

113 - `:"sora-2"`

114

115 - `:"sora-2-pro"`

116

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

118

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

120

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

122

123 - `object: :video`

124

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

126

127 - `:video`

128

129 - `progress: Integer`

130

131 Approximate completion percentage for the generation task.

132

133 - `prompt: String`

134

135 The prompt that was used to generate the video.

136

137 - `remixed_from_video_id: String`

138

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

140

141 - `seconds: String | VideoSeconds`

142

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

144

145 - `String = String`

146

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

148

149 - `:"4"`

150

151 - `:"8"`

152

153 - `:"12"`

154

155 - `size: VideoSize`

156

157 The resolution of the generated video.

158

159 - `:"720x1280"`

160

161 - `:"1280x720"`

162

163 - `:"1024x1792"`

164

165 - `:"1792x1024"`

166

167 - `status: :queued | :in_progress | :completed | :failed`

168

169 Current lifecycle status of the video job.

170

171 - `:queued`

172

173 - `:in_progress`

174

175 - `:completed`

176

177 - `:failed`

178

179### Example

180

181```ruby

182require "openai"

183

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

185

186video = openai.videos.create(prompt: "x")

187

188puts(video)

189```

190

191#### Response

192

193```json

194{

195 "id": "id",

196 "completed_at": 0,

197 "created_at": 0,

198 "error": {

199 "code": "code",

200 "message": "message"

201 },

202 "expires_at": 0,

203 "model": "sora-2",

204 "object": "video",

205 "progress": 0,

206 "prompt": "prompt",

207 "remixed_from_video_id": "remixed_from_video_id",

208 "seconds": "4",

209 "size": "720x1280",

210 "status": "queued"

211}

212```

213

214### Example

215

216```ruby

217require "openai"

218

219openai = OpenAI::Client.new

220

221video = openai.videos.create(prompt: "A calico cat playing a piano on stage")

222

223puts(video)

224```

225

226#### Response

227

228```json

229{

230 "id": "video_123",

231 "object": "video",

232 "model": "sora-2",

233 "status": "queued",

234 "progress": 0,

235 "created_at": 1712697600,

236 "size": "1024x1792",

237 "seconds": "8",

238 "quality": "standard"

239}

240```

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

Create video

Parameters

Returns

Example

Response

Example

Response