Overview
Concrete tool for the Video generation API resource provided by the openai-python SDK.
Description
The Videos Resource module provides Videos (synchronous) and AsyncVideos (asynchronous) resource classes for interacting with the OpenAI Video generation API (Sora). The create() method generates a video from a text prompt, optionally accepting an input_reference image file for guided generation, a model parameter (supporting sora-2 and sora-2-pro), seconds for clip duration (4, 8, or 12), and size for output resolution (e.g., 720x1280, 1280x720). The create_and_poll() convenience method creates a video and polls until processing completes. The retrieve() method fetches a video by ID. The list() method returns a paginated list with cursor-based pagination and sort ordering. The delete() method removes a video. The download_content() method downloads the video file, thumbnail, or spritesheet as binary content. The remix() method creates a new video based on an existing one with an updated prompt. Both classes support with_raw_response and with_streaming_response property accessors. File uploads use multipart form encoding handled automatically by extract_files().
Usage
Use the Videos Resource when you need to generate, manage, or download AI-generated videos through the OpenAI Sora API. This covers the full lifecycle: creating videos from prompts (optionally with image references), polling for completion, listing and retrieving video metadata, downloading rendered content, creating remixes, and cleaning up with delete.
Code Reference
Source Location
Signature
Videos.create()
def create(
self,
*,
prompt: str,
input_reference: FileTypes | Omit = omit,
model: VideoModelParam | Omit = omit,
seconds: VideoSeconds | Omit = omit,
size: VideoSize | Omit = omit,
extra_headers: Headers | None = None,
extra_query: Query | None = None,
extra_body: Body | None = None,
timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> Video: ...
Videos.retrieve()
def retrieve(
self,
video_id: str,
*,
extra_headers: Headers | None = None,
extra_query: Query | None = None,
extra_body: Body | None = None,
timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> Video: ...
Videos.list()
def list(
self,
*,
after: str | Omit = omit,
limit: int | Omit = omit,
order: Literal["asc", "desc"] | Omit = omit,
extra_headers: Headers | None = None,
extra_query: Query | None = None,
extra_body: Body | None = None,
timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> SyncConversationCursorPage[Video]: ...
Videos.delete()
def delete(
self,
video_id: str,
*,
extra_headers: Headers | None = None,
extra_query: Query | None = None,
extra_body: Body | None = None,
timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> VideoDeleteResponse: ...
Videos.download_content()
def download_content(
self,
video_id: str,
*,
variant: Literal["video", "thumbnail", "spritesheet"] | Omit = omit,
extra_headers: Headers | None = None,
extra_query: Query | None = None,
extra_body: Body | None = None,
timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> HttpxBinaryResponseContent: ...
Videos.remix()
def remix(
self,
video_id: str,
*,
prompt: str,
extra_headers: Headers | None = None,
extra_query: Query | None = None,
extra_body: Body | None = None,
timeout: float | httpx.Timeout | None | NotGiven = not_given,
) -> Video: ...
Import
from openai.resources.videos import Videos, AsyncVideos
I/O Contract
Inputs (create)
| Name |
Type |
Required |
Description
|
| prompt |
str |
Yes |
Text prompt that describes the video to generate.
|
| input_reference |
FileTypes |
No |
Optional image reference that guides generation. Sent as multipart form data.
|
| model |
VideoModelParam |
No |
The video generation model to use. Allowed values: sora-2, sora-2-pro. Defaults to sora-2.
|
| seconds |
VideoSeconds |
No |
Clip duration in seconds. Allowed values: 4, 8, 12. Defaults to 4.
|
| size |
VideoSize |
No |
Output resolution (e.g., 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280.
|
Inputs (retrieve / delete)
| Name |
Type |
Required |
Description
|
| video_id |
str |
Yes |
The unique identifier of the video.
|
Inputs (list)
| Name |
Type |
Required |
Description
|
| after |
str |
No |
Cursor identifier for pagination.
|
| limit |
int |
No |
Number of items to retrieve.
|
| order |
Literal["asc", "desc"] |
No |
Sort order by timestamp.
|
Inputs (download_content)
| Name |
Type |
Required |
Description
|
| video_id |
str |
Yes |
The unique identifier of the video.
|
| variant |
Literal["video", "thumbnail", "spritesheet"] |
No |
Which downloadable asset to return. Defaults to the MP4 video.
|
Inputs (remix)
| Name |
Type |
Required |
Description
|
| video_id |
str |
Yes |
The unique identifier of the source video to remix.
|
| prompt |
str |
Yes |
Updated text prompt that directs the remix generation.
|
Outputs
| Name |
Type |
Description
|
| return (create) |
Video |
The created video object with ID, status, and metadata.
|
| return (retrieve) |
Video |
The video object with current status and details.
|
| return (list) |
SyncConversationCursorPage[Video] / AsyncPaginator[Video, AsyncConversationCursorPage[Video]] |
A paginated list of video objects.
|
| return (delete) |
VideoDeleteResponse |
Confirmation of the deletion.
|
| return (download_content) |
HttpxBinaryResponseContent |
The binary content of the video, thumbnail, or spritesheet.
|
| return (remix) |
Video |
The newly created remix video object.
|
Usage Examples
Creating a Video
from openai import OpenAI
client = OpenAI()
video = client.videos.create(
prompt="A serene mountain lake at sunrise with mist rising from the water",
model="sora-2",
seconds=8,
size="1280x720",
)
print(video.id) # "video_abc123"
print(video.status) # "queued"
Create and Poll Until Complete
video = client.videos.create_and_poll(
prompt="A cat playing piano in a jazz club",
model="sora-2",
seconds=4,
)
print(video.status) # "completed"
Downloading Video Content
content = client.videos.download_content("video_abc123", variant="video")
with open("output.mp4", "wb") as f:
f.write(content.content)
Listing Videos
page = client.videos.list(limit=5, order="desc")
for video in page.data:
print(f"{video.id}: {video.status}")
Creating a Remix
remix = client.videos.remix(
"video_abc123",
prompt="Same scene but now it is nighttime with stars",
)
print(remix.id)
Async Usage
from openai import AsyncOpenAI
client = AsyncOpenAI()
video = await client.videos.create(
prompt="Ocean waves crashing on a rocky shore",
seconds=12,
)
completed = await client.videos.poll(video.id)
print(completed.status)
Related Pages
