Videos
Create Video
POST
/
videos
Create Video
curl --request POST \
--url https://api.example.com/videosimport requests
url = "https://api.example.com/videos"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/videos', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/videos",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/videos"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/videos")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/videos")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_body{
"id": "<string>",
"status": "<string>",
"created_at": 123,
"completed_at": 123,
"expires_at": 123,
"model": "<string>",
"prompt": "<string>",
"seconds": 123,
"size": "<string>",
"progress": 123,
"error": {},
"remixed_from_video_id": "<string>"
}Create a new video generation job from a prompt and optional reference assets.
Method Signature
client.videos.create(
prompt="A serene ocean at sunset",
model="sora-2",
seconds=8,
size="1280x720"
)
Parameters
string
required
Text prompt that describes the video to generate.
string
The video generation model to use. Allowed values:
sora-2(default)sora-2-pro
integer
Clip duration in seconds. Allowed values:
4(default)812
string
Output resolution formatted as width x height. Allowed values:
720x1280(default) - vertical/portrait1280x720- horizontal/landscape1024x1792- vertical high-res1792x1024- horizontal high-res
file
Optional image reference that guides generation.
Returns
Returns aVideo object representing the video generation job.
string
Unique identifier for the video job.
string
Current lifecycle status of the video job:
queued- waiting to startin_progress- currently generatingcompleted- successfully finishedfailed- generation failed
integer
Unix timestamp (seconds) for when the job was created.
integer
Unix timestamp (seconds) for when the job completed, if finished.
integer
Unix timestamp (seconds) for when the downloadable assets expire, if set.
string
The video generation model that produced the job.
string
The prompt that was used to generate the video.
integer
Duration of the generated clip in seconds.
string
The resolution of the generated video.
integer
Approximate completion percentage for the generation task (0-100).
object
Error payload that explains why generation failed, if applicable.
string
Identifier of the source video if this video is a remix.
Helper Methods
create_and_poll
Create a video and wait for it to be processed.video = client.videos.create_and_poll(
prompt="A cat playing with a ball of yarn",
model="sora-2",
seconds=8
)
print(f"Video completed with status: {video.status}")
poll
Wait for a video job to finish processing.video = client.videos.create(
prompt="A scenic mountain landscape"
)
# Later, poll for completion
completed_video = client.videos.poll(video.id)
print(f"Status: {completed_video.status}")
Examples
Basic video generation
from openai import OpenAI
client = OpenAI()
video = client.videos.create(
prompt="A beautiful sunset over the ocean with waves crashing",
model="sora-2",
seconds=8,
size="1280x720"
)
print(f"Video ID: {video.id}")
print(f"Status: {video.status}")
print(f"Progress: {video.progress}%")
Generate and wait for completion
from openai import OpenAI
client = OpenAI()
video = client.videos.create_and_poll(
prompt="A bustling city street at night with neon lights",
model="sora-2-pro",
seconds=12,
size="1792x1024"
)
if video.status == "completed":
print(f"Video ready! ID: {video.id}")
print(f"Expires at: {video.expires_at}")
else:
print(f"Video failed with error: {video.error}")
Generate with image reference
from openai import OpenAI
client = OpenAI()
video = client.videos.create(
prompt="Animate this image with gentle movement and lighting changes",
input_reference=open("reference_image.png", "rb"),
model="sora-2",
seconds=4,
size="720x1280"
)
print(f"Video generation started: {video.id}")
Monitor progress with polling
from openai import OpenAI
import time
client = OpenAI()
video = client.videos.create(
prompt="A serene forest with sunlight filtering through trees",
model="sora-2",
seconds=8
)
print(f"Started generation: {video.id}")
# Manual polling with progress updates
while video.status in ["queued", "in_progress"]:
video = client.videos.retrieve(video.id)
print(f"Progress: {video.progress}% - Status: {video.status}")
time.sleep(2)
print(f"Final status: {video.status}")
Vertical video for social media
from openai import OpenAI
client = OpenAI()
video = client.videos.create_and_poll(
prompt="A person walking through a vibrant flower garden",
model="sora-2",
seconds=8,
size="720x1280" # Vertical format for Instagram/TikTok
)
if video.status == "completed":
# Download the video (see download_content documentation)
content = client.videos.download_content(video.id)
with open("social_media_video.mp4", "wb") as f:
f.write(content.read())
Create Video
curl --request POST \
--url https://api.example.com/videosimport requests
url = "https://api.example.com/videos"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/videos', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/videos",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/videos"
req, _ := http.NewRequest("POST", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/videos")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/videos")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_body{
"id": "<string>",
"status": "<string>",
"created_at": 123,
"completed_at": 123,
"expires_at": 123,
"model": "<string>",
"prompt": "<string>",
"seconds": 123,
"size": "<string>",
"progress": 123,
"error": {},
"remixed_from_video_id": "<string>"
}