Skip to main content
The Videos API allows you to generate videos from text prompts using OpenAI’s Sora video generation models.

​
Create Video

Generate a new video from a text prompt: 
video = client.videos.create(
  prompt: "A serene sunset over a mountain lake with gentle waves",
  model: "sora-2",
  seconds: 8,
  size: "1280x720"
)

puts video.id
# => "video_abc123"
puts video.status
# => "in_progress"
​
prompt
string
required
Text description of the video to generate.
​
model
string
The video generation model to use. Options:
  • sora-2 (default)
  • sora-2-pro
​
seconds
integer
Clip duration in seconds. Options: 4, 8, 12. Default: 4.
​
size
string
Output resolution. Options:
  • 720x1280 (portrait)
  • 1280x720 (landscape, default)
  • 1024x1024 (square)
​
input_reference
file
Optional image reference to guide generation. Accepts Pathname, StringIO, IO, or file content string.

​
With Image Reference

Guide video generation with a reference image: 
require "pathname"

video = client.videos.create(
  prompt: "Pan across this landscape at golden hour",
  input_reference: Pathname("landscape.jpg"),
  model: "sora-2-pro",
  seconds: 12
)

​
Retrieve Video

Check the status and metadata of a video generation: 
video = client.videos.retrieve("video_abc123")

puts video.status
# => "completed"
puts video.url
# => "https://..."
​
id
string
Video identifier.
​
status
string
Generation status: in_progress, completed, or failed.
​
url
string
Download URL for the completed video (only present when status is completed).
​
created_at
integer
Unix timestamp of when the video was created.

​
List Videos

Retrieve recently generated videos: 
videos = client.videos.list(limit: 10, order: "desc")

videos.each do |video|
  puts "#{video.id}: #{video.status}"
end

# Pagination
if videos.next_page?
  next_page = videos.next_page
end
​
limit
integer
Number of videos to retrieve (default: 20, max: 100).
​
order
string
Sort order: asc or desc (default).
​
after
string
Cursor for pagination (from previous response).

​
Download Video

Download the generated video content: 
video = client.videos.retrieve("video_abc123")

# Wait for completion
until video.status == "completed"
  sleep 5
  video = client.videos.retrieve(video.id)
end

# Download the video
content = client.videos.download_content(video.id)

# Save to file
File.open("generated_video.mp4", "wb") do |file|
  file.write(content.read)
end
​
video_id
string
required
The ID of the video to download.
​
variant
string
Which asset to download. Default is the full MP4 video.

​
Remix Video

Create a variation of a completed video with a new prompt: 
original = client.videos.retrieve("video_abc123")

remix = client.videos.remix(
  original.id,
  prompt: "Same scene but during a thunderstorm with lightning"
)

puts remix.id
# => "video_def456"
​
video_id
string
required
The ID of the completed video to remix.
​
prompt
string
required
Updated prompt directing the remix generation.

​
Delete Video

Permanently delete a video and its assets: 
result = client.videos.delete("video_abc123")

puts result.deleted
# => true

​
Complete Example

require "openai"

client = OpenAI::Client.new

# Generate a video
video = client.videos.create(
  prompt: "A robot exploring an alien planet with two moons in the sky",
  model: "sora-2-pro",
  seconds: 8,
  size: "1280x720"
)

puts "Video generation started: #{video.id}"

# Poll for completion
loop do
  video = client.videos.retrieve(video.id)
  
  case video.status
  when "completed"
    puts "Video completed!"
    break
  when "failed"
    puts "Video generation failed"
    exit 1
  else
    puts "Status: #{video.status}"
    sleep 10
  end
end

# Download the video
content = client.videos.download_content(video.id)
File.open("robot_planet.mp4", "wb") { |f| f.write(content.read) }

puts "Video saved to robot_planet.mp4"

​
Error Handling

Handle video generation errors: 
begin
  video = client.videos.create(
    prompt: "Video description",
    model: "sora-2"
  )
rescue OpenAI::Errors::BadRequestError => e
  puts "Invalid request: #{e.message}"
rescue OpenAI::Errors::RateLimitError => e
  puts "Rate limit exceeded. Try again later."
end

Images API

Generate images with DALL-E

Audio API

Generate speech and transcribe audio

Responses API

Multi-modal responses

File Uploads

Upload reference images

Build docs developers (and LLMs) love

Get started for freeTalk to us