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

List videos

videos.list(**kwargs) -> ConversationCursorPage<Video { id, completed_at, created_at, 10 more } >
GET
/videos

List recently generated videos for the current project.

Parameters
after: String

Identifier for the last item from the previous pagination request

limit: Integer

Number of items to retrieve

minimum0
maximum100
order: :asc | :desc

Sort order of results by timestamp. Use asc for ascending order or desc for descending order.

Returns
class Video { id, completed_at, created_at, 10 more }

Structured information describing a generated video job.

id: String

Unique identifier for the video job.

completed_at: Integer

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

formatunixtime
created_at: Integer

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

formatunixtime
error: VideoCreateError { code, message, headers, 3 more }

Error payload that explains why generation failed, if applicable.

expires_at: Integer

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

formatunixtime
model: VideoModel

The video generation model that produced the job.

object: :video

The object type, which is always video.

progress: Integer

Approximate completion percentage for the generation task.

prompt: String

The prompt that was used to generate the video.

remixed_from_video_id: String

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

seconds: String | 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: :queued | :in_progress | :completed | :failed

Current lifecycle status of the video job.

List videos

require "openai"

openai = OpenAI::Client.new

page = openai.videos.list

puts(page)

{
  "data": [
    {
      "id": "video_123",
      "object": "video",
      "model": "sora-2",
      "status": "completed",
      "created_at": 1712697600,
      "completed_at": 1712697840,
      "progress": 100,
      "expires_at": null,
      "error": null,
      "prompt": "A calico cat playing a piano on stage",
      "size": "1024x1792",
      "seconds": "8",
      "remixed_from_video_id": null
    }
  ],
  "object": "list",
  "first_id": "video_123",
  "last_id": "video_123",
  "has_more": false
}
Returns Examples
{
  "data": [
    {
      "id": "video_123",
      "object": "video",
      "model": "sora-2",
      "status": "completed",
      "created_at": 1712697600,
      "completed_at": 1712697840,
      "progress": 100,
      "expires_at": null,
      "error": null,
      "prompt": "A calico cat playing a piano on stage",
      "size": "1024x1792",
      "seconds": "8",
      "remixed_from_video_id": null
    }
  ],
  "object": "list",
  "first_id": "video_123",
  "last_id": "video_123",
  "has_more": false
}