Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Create a video

videos.create(VideoCreateParams**kwargs) -> Video
POST/videos

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

ParametersExpand Collapse
prompt: str

Text prompt that describes the video to generate.

minLength1
maxLength32000
input_reference: Optional[InputReference]

Optional reference asset upload or reference object that guides generation.

model: Optional[VideoModelParam]

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

seconds: Optional[VideoSeconds]

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

size: Optional[VideoSize]

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

ReturnsExpand Collapse
class Video: …

Structured information describing a generated video job.

id: str

Unique identifier for the video job.

completed_at: Optional[int]

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

formatunixtime
created_at: int

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

formatunixtime
error: Optional[VideoCreateError]

Error payload that explains why generation failed, if applicable.

expires_at: Optional[int]

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

formatunixtime
model: VideoModel

The video generation model that produced the job.

object: Literal["video"]

The object type, which is always video.

progress: int

Approximate completion percentage for the generation task.

prompt: Optional[str]

The prompt that was used to generate the video.

remixed_from_video_id: Optional[str]

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

seconds: Union[str, VideoSeconds]

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

size: VideoSize

The resolution of the generated video.

status: Literal["queued", "in_progress", "completed", "failed"]

Current lifecycle status of the video job.

Create a video

from openai import OpenAI

client = OpenAI()
video = client.videos.create(
    prompt="A calico cat playing a piano on stage",
)
print(video.id)

{
  "id": "video_123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "size": "1024x1792",
  "seconds": "8",
  "prompt": "A calico cat playing a piano on stage",
  "completed_at": null,
  "expires_at": null,
  "error": null,
  "remixed_from_video_id": null
}
Returns Examples
{
  "id": "video_123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "size": "1024x1792",
  "seconds": "8",
  "prompt": "A calico cat playing a piano on stage",
  "completed_at": null,
  "expires_at": null,
  "error": null,
  "remixed_from_video_id": null
}