Create Video

POST /videos

Create Video

cURL

curl --request POST \
  --url https://api.example.com/videos

import 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

200

{
  "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

prompt · string · required

Text prompt that describes the video to generate.

model · string

The video generation model to use. Allowed values:

• sora-2 (default)
• sora-2-pro

seconds · integer

Clip duration in seconds. Allowed values:

• 4 (default)
• 8
• 12

size · string

Output resolution formatted as width x height. Allowed values:

• 720x1280 (default) - vertical/portrait
• 1280x720 - horizontal/landscape
• 1024x1792 - vertical high-res
• 1792x1024 - horizontal high-res

input_reference · file

Optional image reference that guides generation.

Returns

Returns a Video object representing the video generation job.

id · string

Unique identifier for the video job.

status · string

Current lifecycle status of the video job:

• queued - waiting to start
• in_progress - currently generating
• completed - successfully finished
• failed - generation failed

created_at · integer

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

completed_at · integer

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

expires_at · integer

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

model · string

The video generation model that produced the job.

prompt · string

The prompt that was used to generate the video.

seconds · integer

Duration of the generated clip in seconds.

size · string

The resolution of the generated video.

progress · integer

Approximate completion percentage for the generation task (0-100).

error · object

Error payload that explains why generation failed, if applicable.

remixed_from_video_id · 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())