Videos
Create video
videos.create(**kwargs) -> Video
post /videos
Create a new video generation job from a prompt and optional reference assets.
Parameters
-
prompt: StringText prompt that describes the video to generate.
-
input_reference: String | ImageInputReferenceParamOptional reference asset upload or reference object that guides generation.
-
String = StringOptional reference asset upload or reference object that guides generation.
-
class ImageInputReferenceParam-
file_id: String -
image_url: StringA fully qualified URL or base64-encoded data URL.
-
-
-
model: VideoModelThe 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: VideoSecondsClip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds.
-
:"4" -
:"8" -
:"12"
-
-
size: VideoSizeOutput resolution formatted as width x height (allowed values: 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280.
-
:"720x1280" -
:"1280x720" -
:"1024x1792" -
:"1792x1024"
-
Returns
-
class VideoStructured information describing a generated video job.
-
id: StringUnique identifier for the video job.
-
completed_at: IntegerUnix timestamp (seconds) for when the job completed, if finished.
-
created_at: IntegerUnix timestamp (seconds) for when the job was created.
-
error: VideoCreateErrorError payload that explains why generation failed, if applicable.
-
code: StringA machine-readable error code that was returned.
-
message: StringA human-readable description of the error that was returned.
-
-
expires_at: IntegerUnix timestamp (seconds) for when the downloadable assets expire, if set.
-
model: VideoModelThe 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: :videoThe object type, which is always
video.:video
-
progress: IntegerApproximate completion percentage for the generation task.
-
prompt: StringThe prompt that was used to generate the video.
-
remixed_from_video_id: StringIdentifier of the source video if this video is a remix.
-
seconds: String | VideoSecondsDuration of the generated clip in seconds. For extensions, this is the stitched total duration.
-
String = String -
VideoSeconds = :"4" | :"8" | :"12"-
:"4" -
:"8" -
:"12"
-
-
-
size: VideoSizeThe resolution of the generated video.
-
:"720x1280" -
:"1280x720" -
:"1024x1792" -
:"1792x1024"
-
-
status: :queued | :in_progress | :completed | :failedCurrent 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"
}
Create a new video generation job by editing a source video or existing generated video.
videos.edit(**kwargs) -> Video
post /videos/edits
Create a new video generation job by editing a source video or existing generated video.
Parameters
-
prompt: StringText prompt that describes how to edit the source video.
-
video: String | VideoReferenceInputParam{ id}Reference to the completed video to edit.
-
String = StringReference to the completed video to edit.
-
class VideoReferenceInputParamReference to the completed video to edit.
-
id: StringThe identifier of the completed video.
-
-
Returns
-
class VideoStructured information describing a generated video job.
-
id: StringUnique identifier for the video job.
-
completed_at: IntegerUnix timestamp (seconds) for when the job completed, if finished.
-
created_at: IntegerUnix timestamp (seconds) for when the job was created.
-
error: VideoCreateErrorError payload that explains why generation failed, if applicable.
-
code: StringA machine-readable error code that was returned.
-
message: StringA human-readable description of the error that was returned.
-
-
expires_at: IntegerUnix timestamp (seconds) for when the downloadable assets expire, if set.
-
model: VideoModelThe 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: :videoThe object type, which is always
video.:video
-
progress: IntegerApproximate completion percentage for the generation task.
-
prompt: StringThe prompt that was used to generate the video.
-
remixed_from_video_id: StringIdentifier of the source video if this video is a remix.
-
seconds: String | VideoSecondsDuration of the generated clip in seconds. For extensions, this is the stitched total duration.
-
String = String -
VideoSeconds = :"4" | :"8" | :"12"-
:"4" -
:"8" -
:"12"
-
-
-
size: VideoSizeThe resolution of the generated video.
-
:"720x1280" -
:"1280x720" -
:"1024x1792" -
:"1792x1024"
-
-
status: :queued | :in_progress | :completed | :failedCurrent 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.edit(prompt: "x", video: StringIO.new("Example data"))
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"
}
Create an extension of a completed video.
videos.extend_(**kwargs) -> Video
post /videos/extensions
Create an extension of a completed video.
Parameters
-
prompt: StringUpdated text prompt that directs the extension generation.
-
seconds: VideoSecondsLength of the newly generated extension segment in seconds (allowed values: 4, 8, 12, 16, 20).
-
:"4" -
:"8" -
:"12"
-
-
video: String | VideoReferenceInputParam{ id}Reference to the completed video to extend.
-
String = StringReference to the completed video to extend.
-
class VideoReferenceInputParamReference to the completed video.
-
id: StringThe identifier of the completed video.
-
-
Returns
-
class VideoStructured information describing a generated video job.
-
id: StringUnique identifier for the video job.
-
completed_at: IntegerUnix timestamp (seconds) for when the job completed, if finished.
-
created_at: IntegerUnix timestamp (seconds) for when the job was created.
-
error: VideoCreateErrorError payload that explains why generation failed, if applicable.
-
code: StringA machine-readable error code that was returned.
-
message: StringA human-readable description of the error that was returned.
-
-
expires_at: IntegerUnix timestamp (seconds) for when the downloadable assets expire, if set.
-
model: VideoModelThe 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: :videoThe object type, which is always
video.:video
-
progress: IntegerApproximate completion percentage for the generation task.
-
prompt: StringThe prompt that was used to generate the video.
-
remixed_from_video_id: StringIdentifier of the source video if this video is a remix.
-
seconds: String | VideoSecondsDuration of the generated clip in seconds. For extensions, this is the stitched total duration.
-
String = String -
VideoSeconds = :"4" | :"8" | :"12"-
:"4" -
:"8" -
:"12"
-
-
-
size: VideoSizeThe resolution of the generated video.
-
:"720x1280" -
:"1280x720" -
:"1024x1792" -
:"1792x1024"
-
-
status: :queued | :in_progress | :completed | :failedCurrent 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.extend_(prompt: "x", seconds: :"4", video: StringIO.new("Example data"))
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"
}
Create a character from an uploaded video.
videos.create_character(**kwargs) -> VideoCreateCharacterResponse
post /videos/characters
Create a character from an uploaded video.
Parameters
-
name: StringDisplay name for this API character.
-
video: StringVideo file used to create a character.
Returns
-
class VideoCreateCharacterResponse-
id: StringIdentifier for the character creation cameo.
-
created_at: IntegerUnix timestamp (in seconds) when the character was created.
-
name: StringDisplay name for the character.
-
Example
require "openai"
openai = OpenAI::Client.new(api_key: "My API Key")
response = openai.videos.create_character(name: "x", video: StringIO.new("Example data"))
puts(response)
Response
{
"id": "id",
"created_at": 0,
"name": "name"
}
Fetch a character.
videos.get_character(character_id) -> VideoGetCharacterResponse
get /videos/characters/{character_id}
Fetch a character.
Parameters
character_id: String
Returns
-
class VideoGetCharacterResponse-
id: StringIdentifier for the character creation cameo.
-
created_at: IntegerUnix timestamp (in seconds) when the character was created.
-
name: StringDisplay name for the character.
-
Example
require "openai"
openai = OpenAI::Client.new(api_key: "My API Key")
response = openai.videos.get_character("char_123")
puts(response)
Response
{
"id": "id",
"created_at": 0,
"name": "name"
}
List videos
videos.list(**kwargs) -> ConversationCursorPage<Video>
get /videos
List recently generated videos for the current project.
Parameters
-
after: StringIdentifier for the last item from the previous pagination request
-
limit: IntegerNumber of items to retrieve
-
order: :asc | :descSort order of results by timestamp. Use
ascfor ascending order ordescfor descending order.-
:asc -
:desc
-
Returns
-
class VideoStructured information describing a generated video job.
-
id: StringUnique identifier for the video job.
-
completed_at: IntegerUnix timestamp (seconds) for when the job completed, if finished.
-
created_at: IntegerUnix timestamp (seconds) for when the job was created.
-
error: VideoCreateErrorError payload that explains why generation failed, if applicable.
-
code: StringA machine-readable error code that was returned.
-
message: StringA human-readable description of the error that was returned.
-
-
expires_at: IntegerUnix timestamp (seconds) for when the downloadable assets expire, if set.
-
model: VideoModelThe 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: :videoThe object type, which is always
video.:video
-
progress: IntegerApproximate completion percentage for the generation task.
-
prompt: StringThe prompt that was used to generate the video.
-
remixed_from_video_id: StringIdentifier of the source video if this video is a remix.
-
seconds: String | VideoSecondsDuration of the generated clip in seconds. For extensions, this is the stitched total duration.
-
String = String -
VideoSeconds = :"4" | :"8" | :"12"-
:"4" -
:"8" -
:"12"
-
-
-
size: VideoSizeThe resolution of the generated video.
-
:"720x1280" -
:"1280x720" -
:"1024x1792" -
:"1792x1024"
-
-
status: :queued | :in_progress | :completed | :failedCurrent lifecycle status of the video job.
-
:queued -
:in_progress -
:completed -
:failed
-
-
Example
require "openai"
openai = OpenAI::Client.new(api_key: "My API Key")
page = openai.videos.list
puts(page)
Response
{
"data": [
{
"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"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id",
"object": "list"
}
Example
require "openai"
openai = OpenAI::Client.new
page = openai.videos.list
puts(page)
Response
{
"data": [
{
"id": "video_123",
"object": "video",
"model": "sora-2",
"status": "completed"
}
],
"object": "list"
}
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 VideoStructured information describing a generated video job.
-
id: StringUnique identifier for the video job.
-
completed_at: IntegerUnix timestamp (seconds) for when the job completed, if finished.
-
created_at: IntegerUnix timestamp (seconds) for when the job was created.
-
error: VideoCreateErrorError payload that explains why generation failed, if applicable.
-
code: StringA machine-readable error code that was returned.
-
message: StringA human-readable description of the error that was returned.
-
-
expires_at: IntegerUnix timestamp (seconds) for when the downloadable assets expire, if set.
-
model: VideoModelThe 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: :videoThe object type, which is always
video.:video
-
progress: IntegerApproximate completion percentage for the generation task.
-
prompt: StringThe prompt that was used to generate the video.
-
remixed_from_video_id: StringIdentifier of the source video if this video is a remix.
-
seconds: String | VideoSecondsDuration of the generated clip in seconds. For extensions, this is the stitched total duration.
-
String = String -
VideoSeconds = :"4" | :"8" | :"12"-
:"4" -
:"8" -
:"12"
-
-
-
size: VideoSizeThe resolution of the generated video.
-
:"720x1280" -
:"1280x720" -
:"1024x1792" -
:"1792x1024"
-
-
status: :queued | :in_progress | :completed | :failedCurrent 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)
Delete video
videos.delete(video_id) -> VideoDeleteResponse
delete /videos/{video_id}
Permanently delete a completed or failed video and its stored assets.
Parameters
video_id: String
Returns
-
class VideoDeleteResponseConfirmation payload returned after deleting a video.
-
id: StringIdentifier of the deleted video.
-
deleted: boolIndicates that the video resource was deleted.
-
object: :"video.deleted"The object type that signals the deletion response.
:"video.deleted"
-
Example
require "openai"
openai = OpenAI::Client.new(api_key: "My API Key")
video = openai.videos.delete("video_123")
puts(video)
Response
{
"id": "id",
"deleted": true,
"object": "video.deleted"
}
Example
require "openai"
openai = OpenAI::Client.new
video = openai.videos.delete("video_123")
puts(video)
Remix video
videos.remix(video_id, **kwargs) -> Video
post /videos/{video_id}/remix
Create a remix of a completed video using a refreshed prompt.
Parameters
-
video_id: String -
prompt: StringUpdated text prompt that directs the remix generation.
Returns
-
class VideoStructured information describing a generated video job.
-
id: StringUnique identifier for the video job.
-
completed_at: IntegerUnix timestamp (seconds) for when the job completed, if finished.
-
created_at: IntegerUnix timestamp (seconds) for when the job was created.
-
error: VideoCreateErrorError payload that explains why generation failed, if applicable.
-
code: StringA machine-readable error code that was returned.
-
message: StringA human-readable description of the error that was returned.
-
-
expires_at: IntegerUnix timestamp (seconds) for when the downloadable assets expire, if set.
-
model: VideoModelThe 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: :videoThe object type, which is always
video.:video
-
progress: IntegerApproximate completion percentage for the generation task.
-
prompt: StringThe prompt that was used to generate the video.
-
remixed_from_video_id: StringIdentifier of the source video if this video is a remix.
-
seconds: String | VideoSecondsDuration of the generated clip in seconds. For extensions, this is the stitched total duration.
-
String = String -
VideoSeconds = :"4" | :"8" | :"12"-
:"4" -
:"8" -
:"12"
-
-
-
size: VideoSizeThe resolution of the generated video.
-
:"720x1280" -
:"1280x720" -
:"1024x1792" -
:"1792x1024"
-
-
status: :queued | :in_progress | :completed | :failedCurrent 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.remix("video_123", 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.remix("video_123", prompt: "Extend the scene with the cat taking a bow to the cheering audience")
puts(video)
Response
{
"id": "video_456",
"object": "video",
"model": "sora-2",
"status": "queued",
"progress": 0,
"created_at": 1712698600,
"size": "720x1280",
"seconds": "8",
"remixed_from_video_id": "video_123"
}
Retrieve video content
videos.download_content(video_id, **kwargs) -> StringIO
get /videos/{video_id}/content
Download the generated video bytes or a derived preview asset.
Streams the rendered video content for the specified video job.
Parameters
-
video_id: String -
variant: :video | :thumbnail | :spritesheetWhich downloadable asset to return. Defaults to the MP4 video.
-
:video -
:thumbnail -
:spritesheet
-
Returns
StringIO
Example
require "openai"
openai = OpenAI::Client.new(api_key: "My API Key")
response = openai.videos.download_content("video_123")
puts(response)
Example
require "openai"
openai = OpenAI::Client.new
response = openai.videos.download_content("video_123")
puts(response)
Domain Types
Image Input Reference Param
-
class ImageInputReferenceParam-
file_id: String -
image_url: StringA fully qualified URL or base64-encoded data URL.
-
Video
-
class VideoStructured information describing a generated video job.
-
id: StringUnique identifier for the video job.
-
completed_at: IntegerUnix timestamp (seconds) for when the job completed, if finished.
-
created_at: IntegerUnix timestamp (seconds) for when the job was created.
-
error: VideoCreateErrorError payload that explains why generation failed, if applicable.
-
code: StringA machine-readable error code that was returned.
-
message: StringA human-readable description of the error that was returned.
-
-
expires_at: IntegerUnix timestamp (seconds) for when the downloadable assets expire, if set.
-
model: VideoModelThe 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: :videoThe object type, which is always
video.:video
-
progress: IntegerApproximate completion percentage for the generation task.
-
prompt: StringThe prompt that was used to generate the video.
-
remixed_from_video_id: StringIdentifier of the source video if this video is a remix.
-
seconds: String | VideoSecondsDuration of the generated clip in seconds. For extensions, this is the stitched total duration.
-
String = String -
VideoSeconds = :"4" | :"8" | :"12"-
:"4" -
:"8" -
:"12"
-
-
-
size: VideoSizeThe resolution of the generated video.
-
:"720x1280" -
:"1280x720" -
:"1024x1792" -
:"1792x1024"
-
-
status: :queued | :in_progress | :completed | :failedCurrent lifecycle status of the video job.
-
:queued -
:in_progress -
:completed -
:failed
-
-
Video Create Error
-
class VideoCreateErrorAn error that occurred while generating the response.
-
code: StringA machine-readable error code that was returned.
-
message: StringA human-readable description of the error that was returned.
-
Video Model
-
VideoModel = String | :"sora-2" | :"sora-2-pro" | :"sora-2-2025-10-06" | 2 more-
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"
-
-
Video Seconds
-
VideoSeconds = :"4" | :"8" | :"12"-
:"4" -
:"8" -
:"12"
-
Video Size
-
VideoSize = :"720x1280" | :"1280x720" | :"1024x1792" | :"1792x1024"-
:"720x1280" -
:"1280x720" -
:"1024x1792" -
:"1792x1024"
-
Video Create Character Response
-
class VideoCreateCharacterResponse-
id: StringIdentifier for the character creation cameo.
-
created_at: IntegerUnix timestamp (in seconds) when the character was created.
-
name: StringDisplay name for the character.
-
Video Get Character Response
-
class VideoGetCharacterResponse-
id: StringIdentifier for the character creation cameo.
-
created_at: IntegerUnix timestamp (in seconds) when the character was created.
-
name: StringDisplay name for the character.
-
Video Delete Response
-
class VideoDeleteResponseConfirmation payload returned after deleting a video.
-
id: StringIdentifier of the deleted video.
-
deleted: boolIndicates that the video resource was deleted.
-
object: :"video.deleted"The object type that signals the deletion response.
:"video.deleted"
-