Videos

Create video

post /videos

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

Body Parameters

prompt: string

Text prompt that describes the video to generate.
input_reference: optional ImageInputReferenceParam

Optional reference object that guides generation. Provide exactly one of image_url or file_id.
- file_id: optional string
- image_url: optional string
  
  A fully qualified URL or base64-encoded data URL.
model: optional VideoModel

The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to sora-2.
- string
- "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more
  - "sora-2"
  - "sora-2-pro"
  - "sora-2-2025-10-06"
  - "sora-2-pro-2025-10-06"
  - "sora-2-2025-12-08"
seconds: optional VideoSeconds

Clip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds.
- "4"
- "8"
- "12"
size: optional VideoSize

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

Returns

Video object { id, completed_at, created_at, 10 more }

Structured information describing a generated video job.
- id: string
  
  Unique identifier for the video job.
- completed_at: number
  
  Unix timestamp (seconds) for when the job completed, if finished.
- created_at: number
  
  Unix timestamp (seconds) for when the job was created.
- error: VideoCreateError
  
  Error payload that explains why generation failed, if applicable.
  - code: string
    
    A machine-readable error code that was returned.
  - message: string
    
    A human-readable description of the error that was returned.
- expires_at: number
  
  Unix timestamp (seconds) for when the downloadable assets expire, if set.
- model: VideoModel
  
  The video generation model that produced the job.
  - string
  - "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more
    - "sora-2"
    - "sora-2-pro"
    - "sora-2-2025-10-06"
    - "sora-2-pro-2025-10-06"
    - "sora-2-2025-12-08"
- object: "video"
  
  The object type, which is always video.
  - "video"
- progress: number
  
  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
  
  Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
- size: VideoSize
  
  The resolution of the generated video.
  - "720x1280"
  - "1280x720"
  - "1024x1792"
  - "1792x1024"
- status: "queued" or "in_progress" or "completed" or "failed"
  
  Current lifecycle status of the video job.
  - "queued"
  - "in_progress"
  - "completed"
  - "failed"

Example

curl https://api.openai.com/v1/videos \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "prompt": "x"
        }'

Response

{
  "id": "id",
  "completed_at": 0,
  "created_at": 0,
  "error": {
    "code": "code",
    "message": "message"
  },
  "expires_at": 0,
  "model": "sora-2",
  "object": "video",
  "progress": 0,
  "prompt": "prompt",
  "remixed_from_video_id": "remixed_from_video_id",
  "seconds": "string",
  "size": "720x1280",
  "status": "queued"
}

Example

curl https://api.openai.com/v1/videos \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "model=sora-2" \
  -F "prompt=A calico cat playing a piano on stage"

Response

{
  "id": "video_123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "size": "1024x1792",
  "seconds": "8",
  "quality": "standard"
}

Create a character from an uploaded video.

post /videos/characters

Create a character from an uploaded video.

Returns

id: string

Identifier for the character creation cameo.
created_at: number

Unix timestamp (in seconds) when the character was created.
name: string

Display name for the character.

Example

curl https://api.openai.com/v1/videos/characters \
    -H 'Content-Type: multipart/form-data' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -F name=x \
    -F 'video=@/path/to/video'

Response

{
  "id": "id",
  "created_at": 0,
  "name": "name"
}

Delete video

delete /videos/{video_id}

Permanently delete a completed or failed video and its stored assets.

Path Parameters

video_id: string

Returns

id: string

Identifier of the deleted video.
deleted: boolean

Indicates that the video resource was deleted.
object: "video.deleted"

The object type that signals the deletion response.
- "video.deleted"

Example

curl https://api.openai.com/v1/videos/$VIDEO_ID \
    -X DELETE \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "id": "id",
  "deleted": true,
  "object": "video.deleted"
}

Retrieve video content

get /videos/{video_id}/content

Download the generated video bytes or a derived preview asset.

Streams the rendered video content for the specified video job.

Path Parameters

video_id: string

Query Parameters

variant: optional "video" or "thumbnail" or "spritesheet"

Which downloadable asset to return. Defaults to the MP4 video.
- "video"
- "thumbnail"
- "spritesheet"

Example

curl https://api.openai.com/v1/videos/$VIDEO_ID/content \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Create a new video generation job by editing a source video or existing generated video.

post /videos/edits

Create a new video generation job by editing a source video or existing generated video.

Body Parameters

prompt: string

Text prompt that describes how to edit the source video.
video: object { id }

Reference to the completed video to edit.
- id: string
  
  The identifier of the completed video.

Returns

Video object { id, completed_at, created_at, 10 more }

Structured information describing a generated video job.
- id: string
  
  Unique identifier for the video job.
- completed_at: number
  
  Unix timestamp (seconds) for when the job completed, if finished.
- created_at: number
  
  Unix timestamp (seconds) for when the job was created.
- error: VideoCreateError
  
  Error payload that explains why generation failed, if applicable.
  - code: string
    
    A machine-readable error code that was returned.
  - message: string
    
    A human-readable description of the error that was returned.
- expires_at: number
  
  Unix timestamp (seconds) for when the downloadable assets expire, if set.
- model: VideoModel
  
  The video generation model that produced the job.
  - string
  - "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more
    - "sora-2"
    - "sora-2-pro"
    - "sora-2-2025-10-06"
    - "sora-2-pro-2025-10-06"
    - "sora-2-2025-12-08"
- object: "video"
  
  The object type, which is always video.
  - "video"
- progress: number
  
  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
  
  Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
- size: VideoSize
  
  The resolution of the generated video.
  - "720x1280"
  - "1280x720"
  - "1024x1792"
  - "1792x1024"
- status: "queued" or "in_progress" or "completed" or "failed"
  
  Current lifecycle status of the video job.
  - "queued"
  - "in_progress"
  - "completed"
  - "failed"

Example

curl https://api.openai.com/v1/videos/edits \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "prompt": "x",
          "video": {
            "id": "video_123"
          }
        }'

Response

{
  "id": "id",
  "completed_at": 0,
  "created_at": 0,
  "error": {
    "code": "code",
    "message": "message"
  },
  "expires_at": 0,
  "model": "sora-2",
  "object": "video",
  "progress": 0,
  "prompt": "prompt",
  "remixed_from_video_id": "remixed_from_video_id",
  "seconds": "string",
  "size": "720x1280",
  "status": "queued"
}

Create an extension of a completed video.

post /videos/extensions

Create an extension of a completed video.

Body Parameters

prompt: string

Updated text prompt that directs the extension generation.
seconds: VideoSeconds

Length of the newly generated extension segment in seconds (allowed values: 4, 8, 12, 16, 20).
- "4"
- "8"
- "12"
video: object { id }

Reference to the completed video to extend.
- id: string
  
  The identifier of the completed video.

Returns

Video object { id, completed_at, created_at, 10 more }

Structured information describing a generated video job.
- id: string
  
  Unique identifier for the video job.
- completed_at: number
  
  Unix timestamp (seconds) for when the job completed, if finished.
- created_at: number
  
  Unix timestamp (seconds) for when the job was created.
- error: VideoCreateError
  
  Error payload that explains why generation failed, if applicable.
  - code: string
    
    A machine-readable error code that was returned.
  - message: string
    
    A human-readable description of the error that was returned.
- expires_at: number
  
  Unix timestamp (seconds) for when the downloadable assets expire, if set.
- model: VideoModel
  
  The video generation model that produced the job.
  - string
  - "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more
    - "sora-2"
    - "sora-2-pro"
    - "sora-2-2025-10-06"
    - "sora-2-pro-2025-10-06"
    - "sora-2-2025-12-08"
- object: "video"
  
  The object type, which is always video.
  - "video"
- progress: number
  
  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
  
  Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
- size: VideoSize
  
  The resolution of the generated video.
  - "720x1280"
  - "1280x720"
  - "1024x1792"
  - "1792x1024"
- status: "queued" or "in_progress" or "completed" or "failed"
  
  Current lifecycle status of the video job.
  - "queued"
  - "in_progress"
  - "completed"
  - "failed"

Example

curl https://api.openai.com/v1/videos/extensions \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "prompt": "x",
          "seconds": "4",
          "video": {
            "id": "video_123"
          }
        }'

Response

{
  "id": "id",
  "completed_at": 0,
  "created_at": 0,
  "error": {
    "code": "code",
    "message": "message"
  },
  "expires_at": 0,
  "model": "sora-2",
  "object": "video",
  "progress": 0,
  "prompt": "prompt",
  "remixed_from_video_id": "remixed_from_video_id",
  "seconds": "string",
  "size": "720x1280",
  "status": "queued"
}

Fetch a character.

get /videos/characters/{character_id}

Fetch a character.

Path Parameters

character_id: string

Returns

id: string

Identifier for the character creation cameo.
created_at: number

Unix timestamp (in seconds) when the character was created.
name: string

Display name for the character.

Example

curl https://api.openai.com/v1/videos/characters/$CHARACTER_ID \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "id": "id",
  "created_at": 0,
  "name": "name"
}

get /videos

List recently generated videos for the current project.

Query Parameters

after: optional string

Identifier for the last item from the previous pagination request
limit: optional number

Number of items to retrieve
order: optional "asc" or "desc"

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

Returns

data: array of Video

A list of items
- id: string
  
  Unique identifier for the video job.
- completed_at: number
  
  Unix timestamp (seconds) for when the job completed, if finished.
- created_at: number
  
  Unix timestamp (seconds) for when the job was created.
- error: VideoCreateError
  
  Error payload that explains why generation failed, if applicable.
  - code: string
    
    A machine-readable error code that was returned.
  - message: string
    
    A human-readable description of the error that was returned.
- expires_at: number
  
  Unix timestamp (seconds) for when the downloadable assets expire, if set.
- model: VideoModel
  
  The video generation model that produced the job.
  - string
  - "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more
    - "sora-2"
    - "sora-2-pro"
    - "sora-2-2025-10-06"
    - "sora-2-pro-2025-10-06"
    - "sora-2-2025-12-08"
- object: "video"
  
  The object type, which is always video.
  - "video"
- progress: number
  
  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
  
  Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
- size: VideoSize
  
  The resolution of the generated video.
  - "720x1280"
  - "1280x720"
  - "1024x1792"
  - "1792x1024"
- status: "queued" or "in_progress" or "completed" or "failed"
  
  Current lifecycle status of the video job.
  - "queued"
  - "in_progress"
  - "completed"
  - "failed"
first_id: string

The ID of the first item in the list.
has_more: boolean

Whether there are more items available.
last_id: string

The ID of the last item in the list.
object: "list"

The type of object returned, must be list.
- "list"

Example

curl https://api.openai.com/v1/videos \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "data": [
    {
      "id": "id",
      "completed_at": 0,
      "created_at": 0,
      "error": {
        "code": "code",
        "message": "message"
      },
      "expires_at": 0,
      "model": "sora-2",
      "object": "video",
      "progress": 0,
      "prompt": "prompt",
      "remixed_from_video_id": "remixed_from_video_id",
      "seconds": "string",
      "size": "720x1280",
      "status": "queued"
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}

Example

curl https://api.openai.com/v1/videos \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "data": [
    {
      "id": "video_123",
      "object": "video",
      "model": "sora-2",
      "status": "completed"
    }
  ],
  "object": "list"
}

Remix video

post /videos/{video_id}/remix

Create a remix of a completed video using a refreshed prompt.

Path Parameters

video_id: string

Body Parameters

prompt: string

Updated text prompt that directs the remix generation.

Returns

Video object { id, completed_at, created_at, 10 more }

Structured information describing a generated video job.
- id: string
  
  Unique identifier for the video job.
- completed_at: number
  
  Unix timestamp (seconds) for when the job completed, if finished.
- created_at: number
  
  Unix timestamp (seconds) for when the job was created.
- error: VideoCreateError
  
  Error payload that explains why generation failed, if applicable.
  - code: string
    
    A machine-readable error code that was returned.
  - message: string
    
    A human-readable description of the error that was returned.
- expires_at: number
  
  Unix timestamp (seconds) for when the downloadable assets expire, if set.
- model: VideoModel
  
  The video generation model that produced the job.
  - string
  - "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more
    - "sora-2"
    - "sora-2-pro"
    - "sora-2-2025-10-06"
    - "sora-2-pro-2025-10-06"
    - "sora-2-2025-12-08"
- object: "video"
  
  The object type, which is always video.
  - "video"
- progress: number
  
  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
  
  Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
- size: VideoSize
  
  The resolution of the generated video.
  - "720x1280"
  - "1280x720"
  - "1024x1792"
  - "1792x1024"
- status: "queued" or "in_progress" or "completed" or "failed"
  
  Current lifecycle status of the video job.
  - "queued"
  - "in_progress"
  - "completed"
  - "failed"

Example

curl https://api.openai.com/v1/videos/$VIDEO_ID/remix \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
          "prompt": "x"
        }'

Response

{
  "id": "id",
  "completed_at": 0,
  "created_at": 0,
  "error": {
    "code": "code",
    "message": "message"
  },
  "expires_at": 0,
  "model": "sora-2",
  "object": "video",
  "progress": 0,
  "prompt": "prompt",
  "remixed_from_video_id": "remixed_from_video_id",
  "seconds": "string",
  "size": "720x1280",
  "status": "queued"
}

Example

curl -X POST https://api.openai.com/v1/videos/video_123/remix \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Extend the scene with the cat taking a bow to the cheering audience"
  }'

Response

{
  "id": "video_456",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712698600,
  "size": "720x1280",
  "seconds": "8",
  "remixed_from_video_id": "video_123"
}

Retrieve video

get /videos/{video_id}

Fetch the latest metadata for a generated video.

Path Parameters

video_id: string

Returns

Video object { id, completed_at, created_at, 10 more }

Structured information describing a generated video job.
- id: string
  
  Unique identifier for the video job.
- completed_at: number
  
  Unix timestamp (seconds) for when the job completed, if finished.
- created_at: number
  
  Unix timestamp (seconds) for when the job was created.
- error: VideoCreateError
  
  Error payload that explains why generation failed, if applicable.
  - code: string
    
    A machine-readable error code that was returned.
  - message: string
    
    A human-readable description of the error that was returned.
- expires_at: number
  
  Unix timestamp (seconds) for when the downloadable assets expire, if set.
- model: VideoModel
  
  The video generation model that produced the job.
  - string
  - "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more
    - "sora-2"
    - "sora-2-pro"
    - "sora-2-2025-10-06"
    - "sora-2-pro-2025-10-06"
    - "sora-2-2025-12-08"
- object: "video"
  
  The object type, which is always video.
  - "video"
- progress: number
  
  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
  
  Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
- size: VideoSize
  
  The resolution of the generated video.
  - "720x1280"
  - "1280x720"
  - "1024x1792"
  - "1792x1024"
- status: "queued" or "in_progress" or "completed" or "failed"
  
  Current lifecycle status of the video job.
  - "queued"
  - "in_progress"
  - "completed"
  - "failed"

Example

curl https://api.openai.com/v1/videos/$VIDEO_ID \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "id": "id",
  "completed_at": 0,
  "created_at": 0,
  "error": {
    "code": "code",
    "message": "message"
  },
  "expires_at": 0,
  "model": "sora-2",
  "object": "video",
  "progress": 0,
  "prompt": "prompt",
  "remixed_from_video_id": "remixed_from_video_id",
  "seconds": "string",
  "size": "720x1280",
  "status": "queued"
}

Domain Types

Image Input Reference Param

ImageInputReferenceParam object { file_id, image_url }
- file_id: optional string
- image_url: optional string
  
  A fully qualified URL or base64-encoded data URL.

Video

Video object { id, completed_at, created_at, 10 more }

Structured information describing a generated video job.
- id: string
  
  Unique identifier for the video job.
- completed_at: number
  
  Unix timestamp (seconds) for when the job completed, if finished.
- created_at: number
  
  Unix timestamp (seconds) for when the job was created.
- error: VideoCreateError
  
  Error payload that explains why generation failed, if applicable.
  - code: string
    
    A machine-readable error code that was returned.
  - message: string
    
    A human-readable description of the error that was returned.
- expires_at: number
  
  Unix timestamp (seconds) for when the downloadable assets expire, if set.
- model: VideoModel
  
  The video generation model that produced the job.
  - string
  - "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more
    - "sora-2"
    - "sora-2-pro"
    - "sora-2-2025-10-06"
    - "sora-2-pro-2025-10-06"
    - "sora-2-2025-12-08"
- object: "video"
  
  The object type, which is always video.
  - "video"
- progress: number
  
  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
  
  Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
- size: VideoSize
  
  The resolution of the generated video.
  - "720x1280"
  - "1280x720"
  - "1024x1792"
  - "1792x1024"
- status: "queued" or "in_progress" or "completed" or "failed"
  
  Current lifecycle status of the video job.
  - "queued"
  - "in_progress"
  - "completed"
  - "failed"

Video Create Character Response

VideoCreateCharacterResponse object { id, created_at, name }
- id: string
  
  Identifier for the character creation cameo.
- created_at: number
  
  Unix timestamp (in seconds) when the character was created.
- name: string
  
  Display name for the character.

Video Create Error

VideoCreateError object { code, message }

An error that occurred while generating the response.
- code: string
  
  A machine-readable error code that was returned.
- message: string
  
  A human-readable description of the error that was returned.

Video Delete Response

VideoDeleteResponse object { id, deleted, object }

Confirmation payload returned after deleting a video.
- id: string
  
  Identifier of the deleted video.
- deleted: boolean
  
  Indicates that the video resource was deleted.
- object: "video.deleted"
  
  The object type that signals the deletion response.
  - "video.deleted"

Video Get Character Response

VideoGetCharacterResponse object { id, created_at, name }
- id: string
  
  Identifier for the character creation cameo.
- created_at: number
  
  Unix timestamp (in seconds) when the character was created.
- name: string
  
  Display name for the character.

Video Model

VideoModel = string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more
- string
- "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more
  - "sora-2"
  - "sora-2-pro"
  - "sora-2-2025-10-06"
  - "sora-2-pro-2025-10-06"
  - "sora-2-2025-12-08"

Video Seconds

VideoSeconds = "4" or "8" or "12"
- "4"
- "8"
- "12"

Video Size

VideoSize = "720x1280" or "1280x720" or "1024x1792" or "1792x1024"
- "720x1280"
- "1280x720"
- "1024x1792"
- "1792x1024"

resources/videos/index.md +205 −205

188 "progress": 0,188 "progress": 0,

189 "prompt": "prompt",189 "prompt": "prompt",

190 "remixed_from_video_id": "remixed_from_video_id",190 "remixed_from_video_id": "remixed_from_video_id",

191 "seconds": "seconds",191 "seconds": "string",

192 "size": "720x1280",192 "size": "720x1280",

193 "status": "queued"193 "status": "queued"

194}194}

219}219}

220```220```

221 221

222## Create a character from an uploaded video.

223

224**post** `/videos/characters`

225

226Create a character from an uploaded video.

227

228### Returns

229

230- `id: string`

231

232 Identifier for the character creation cameo.

233

234- `created_at: number`

235

236 Unix timestamp (in seconds) when the character was created.

237

238- `name: string`

239

240 Display name for the character.

241

242### Example

243

244```http

245curl https://api.openai.com/v1/videos/characters \

246 -H 'Content-Type: multipart/form-data' \

247 -H "Authorization: Bearer $OPENAI_API_KEY" \

248 -F name=x \

249 -F 'video=@/path/to/video'

250```

251

252#### Response

253

254```json

255{

256 "id": "id",

257 "created_at": 0,

258 "name": "name"

259}

260```

261

262## Delete video

263

264**delete** `/videos/{video_id}`

265

266Permanently delete a completed or failed video and its stored assets.

267

268### Path Parameters

269

270- `video_id: string`

271

272### Returns

273

274- `id: string`

275

276 Identifier of the deleted video.

277

278- `deleted: boolean`

279

280 Indicates that the video resource was deleted.

281

282- `object: "video.deleted"`

283

284 The object type that signals the deletion response.

285

286 - `"video.deleted"`

287

288### Example

289

290```http

291curl https://api.openai.com/v1/videos/$VIDEO_ID \

292 -X DELETE \

293 -H "Authorization: Bearer $OPENAI_API_KEY"

294```

295

296#### Response

297

298```json

299{

300 "id": "id",

301 "deleted": true,

302 "object": "video.deleted"

303}

304```

305

306## Retrieve video content

307

308**get** `/videos/{video_id}/content`

309

310Download the generated video bytes or a derived preview asset.

311

312Streams the rendered video content for the specified video job.

313

314### Path Parameters

315

316- `video_id: string`

317

318### Query Parameters

319

320- `variant: optional "video" or "thumbnail" or "spritesheet"`

321

322 Which downloadable asset to return. Defaults to the MP4 video.

323

324 - `"video"`

325

326 - `"thumbnail"`

327

328 - `"spritesheet"`

329

330### Example

331

332```http

333curl https://api.openai.com/v1/videos/$VIDEO_ID/content \

334 -H "Authorization: Bearer $OPENAI_API_KEY"

335```

336

222## Create a new video generation job by editing a source video or existing generated video.337## Create a new video generation job by editing a source video or existing generated video.

223 338

224**post** `/videos/edits`339**post** `/videos/edits`

368 "progress": 0,483 "progress": 0,

369 "prompt": "prompt",484 "prompt": "prompt",

370 "remixed_from_video_id": "remixed_from_video_id",485 "remixed_from_video_id": "remixed_from_video_id",

371 "seconds": "seconds",486 "seconds": "string",

372 "size": "720x1280",487 "size": "720x1280",

373 "status": "queued"488 "status": "queued"

374}489}

534 "progress": 0,649 "progress": 0,

535 "prompt": "prompt",650 "prompt": "prompt",

536 "remixed_from_video_id": "remixed_from_video_id",651 "remixed_from_video_id": "remixed_from_video_id",

537 "seconds": "seconds",652 "seconds": "string",

538 "size": "720x1280",653 "size": "720x1280",

539 "status": "queued"654 "status": "queued"

540}655}

541```656```

542 657

543## Create a character from an uploaded video.

~~544~~

545**post** `/videos/characters`

~~546~~

547Create a character from an uploaded video.

~~548~~

549### Returns

~~550~~

551- `id: string`

~~552~~

553 Identifier for the character creation cameo.

~~554~~

555- `created_at: number`

~~556~~

557 Unix timestamp (in seconds) when the character was created.

~~558~~

559- `name: string`

~~560~~

561 Display name for the character.

~~562~~

563### Example

~~564~~

565```http

566curl https://api.openai.com/v1/videos/characters \

567 -H 'Content-Type: multipart/form-data' \

568 -H "Authorization: Bearer $OPENAI_API_KEY" \

569 -F name=x \

570 -F 'video=@/path/to/video'

571```

~~572~~

573#### Response

~~574~~

575```json

576{

577 "id": "id",

578 "created_at": 0,

579 "name": "name"

580}

581```

~~582~~

583## Fetch a character.658## Fetch a character.

584 659

585**get** `/videos/characters/{character_id}`660**get** `/videos/characters/{character_id}`

787 "progress": 0,862 "progress": 0,

788 "prompt": "prompt",863 "prompt": "prompt",

789 "remixed_from_video_id": "remixed_from_video_id",864 "remixed_from_video_id": "remixed_from_video_id",

790 "seconds": "seconds",865 "seconds": "string",

791 "size": "720x1280",866 "size": "720x1280",

792 "status": "queued"867 "status": "queued"

793 }868 }

822}897}

823```898```

824 899

825## Retrieve video900## Remix video

826 901

827**get** `/videos/{video_id}`902**post** `/videos/{video_id}/remix`

828 903

829Fetch the latest metadata for a generated video.904Create a remix of a completed video using a refreshed prompt.

830 905

831### Path Parameters906### Path Parameters

832 907

833- `video_id: string`908- `video_id: string`

834 909

910### Body Parameters

911

912- `prompt: string`

913

914 Updated text prompt that directs the remix generation.

915

835### Returns916### Returns

836 917

837- `Video object { id, completed_at, created_at, 10 more }`918- `Video object { id, completed_at, created_at, 10 more }`

933### Example1014### Example

934 1015

935```http1016```http

936curl https://api.openai.com/v1/videos/$VIDEO_ID \1017curl https://api.openai.com/v1/videos/$VIDEO_ID/remix \

937 -H "Authorization: Bearer $OPENAI_API_KEY"1018 -H 'Content-Type: application/json' \

1019 -H "Authorization: Bearer $OPENAI_API_KEY" \

1020 -d '{

1021 "prompt": "x"

1022 }'

938```1023```

939 1024

940#### Response1025#### Response

954 "progress": 0,1039 "progress": 0,

955 "prompt": "prompt",1040 "prompt": "prompt",

956 "remixed_from_video_id": "remixed_from_video_id",1041 "remixed_from_video_id": "remixed_from_video_id",

957 "seconds": "seconds",1042 "seconds": "string",

958 "size": "720x1280",1043 "size": "720x1280",

959 "status": "queued"1044 "status": "queued"

960}1045}

961```1046```

962 1047

963## Delete video

~~964~~

965**delete** `/videos/{video_id}`

~~966~~

967Permanently delete a completed or failed video and its stored assets.

~~968~~

969### Path Parameters

~~970~~

971- `video_id: string`

~~972~~

973### Returns

~~974~~

975- `id: string`

~~976~~

977 Identifier of the deleted video.

~~978~~

979- `deleted: boolean`

~~980~~

981 Indicates that the video resource was deleted.

~~982~~

983- `object: "video.deleted"`

~~984~~

985 The object type that signals the deletion response.

~~986~~

987 - `"video.deleted"`

~~988~~

989### Example1048### Example

990 1049

991```http1050```http

992curl https://api.openai.com/v1/videos/$VIDEO_ID \1051curl -X POST https://api.openai.com/v1/videos/video_123/remix \

993 -X DELETE \1052 -H "Authorization: Bearer $OPENAI_API_KEY" \

994 -H "Authorization: Bearer $OPENAI_API_KEY"1053 -H "Content-Type: application/json" \

1054 -d '{

1055 "prompt": "Extend the scene with the cat taking a bow to the cheering audience"

1056 }'

995```1057```

996 1058

997#### Response1059#### Response

998 1060

999```json1061```json

1000{1062{

1001 "id": "id",1063 "id": "video_456",

1002 "deleted": true,1064 "object": "video",

1003 "object": "video.deleted"1065 "model": "sora-2",

1066 "status": "queued",

1067 "progress": 0,

1068 "created_at": 1712698600,

1069 "size": "720x1280",

1070 "seconds": "8",

1071 "remixed_from_video_id": "video_123"

1004}1072}

1005```1073```

1006 1074

1007## Remix video1075## Retrieve video

1008 1076

1009**post** `/videos/{video_id}/remix`1077**get** `/videos/{video_id}`

1010 1078

1011Create a remix of a completed video using a refreshed prompt.1079Fetch the latest metadata for a generated video.

1012 1080

1013### Path Parameters1081### Path Parameters

1014 1082

1015- `video_id: string`1083- `video_id: string`

1016 1084

1017### Body Parameters

~~1018~~

1019- `prompt: string`

~~1020~~

1021 Updated text prompt that directs the remix generation.

~~1022~~

1023### Returns1085### Returns

1024 1086

1025- `Video object { id, completed_at, created_at, 10 more }`1087- `Video object { id, completed_at, created_at, 10 more }`

1121### Example1183### Example

1122 1184

1123```http1185```http

1124curl https://api.openai.com/v1/videos/$VIDEO_ID/remix \1186curl https://api.openai.com/v1/videos/$VIDEO_ID \

1125 -H 'Content-Type: application/json' \1187 -H "Authorization: Bearer $OPENAI_API_KEY"

1126 -H "Authorization: Bearer $OPENAI_API_KEY" \

1127 -d '{

1128 "prompt": "x"

1129 }'

1130```1188```

1131 1189

1132#### Response1190#### Response

1146 "progress": 0,1204 "progress": 0,

1147 "prompt": "prompt",1205 "prompt": "prompt",

1148 "remixed_from_video_id": "remixed_from_video_id",1206 "remixed_from_video_id": "remixed_from_video_id",

1149 "seconds": "seconds",1207 "seconds": "string",

1150 "size": "720x1280",1208 "size": "720x1280",

1151 "status": "queued"1209 "status": "queued"

1152}1210}

1153```1211```

1154 1212

1155### Example

~~1156~~

1157```http

1158curl -X POST https://api.openai.com/v1/videos/video_123/remix \

1159 -H "Authorization: Bearer $OPENAI_API_KEY" \

1160 -H "Content-Type: application/json" \

1161 -d '{

1162 "prompt": "Extend the scene with the cat taking a bow to the cheering audience"

1163 }'

1164```

~~1165~~

1166#### Response

~~1167~~

1168```json

1169{

1170 "id": "video_456",

1171 "object": "video",

1172 "model": "sora-2",

1173 "status": "queued",

1174 "progress": 0,

1175 "created_at": 1712698600,

1176 "size": "720x1280",

1177 "seconds": "8",

1178 "remixed_from_video_id": "video_123"

1179}

1180```

~~1181~~

1182## Retrieve video content

~~1183~~

1184**get** `/videos/{video_id}/content`

~~1185~~

1186Download the generated video bytes or a derived preview asset.

~~1187~~

1188Streams the rendered video content for the specified video job.

~~1189~~

1190### Path Parameters

~~1191~~

1192- `video_id: string`

~~1193~~

1194### Query Parameters

~~1195~~

1196- `variant: optional "video" or "thumbnail" or "spritesheet"`

~~1197~~

1198 Which downloadable asset to return. Defaults to the MP4 video.

~~1199~~

1200 - `"video"`

~~1201~~

1202 - `"thumbnail"`

~~1203~~

1204 - `"spritesheet"`

~~1205~~

1206### Example

~~1207~~

1208```http

1209curl https://api.openai.com/v1/videos/$VIDEO_ID/content \

1210 -H "Authorization: Bearer $OPENAI_API_KEY"

1211```

~~1212~~

1213## Domain Types1213## Domain Types

1214 1214

1215### Image Input Reference Param1215### Image Input Reference Param

1320 1320

1321 - `"failed"`1321 - `"failed"`

1322 1322

1323### Video Create Error1323### Video Create Character Response

~~1324~~

1325- `VideoCreateError object { code, message }`

~~1326~~

1327 An error that occurred while generating the response.

1328 1324

1329 - `code: string`1325- `VideoCreateCharacterResponse object { id, created_at, name }`

1330 1326

1331 A machine-readable error code that was returned.1327 - `id: string`

1332 1328

1333 - `message: string`1329 Identifier for the character creation cameo.

1334 1330

1335 A human-readable description of the error that was returned.1331 - `created_at: number`

1336 1332

1337### Video Model1333 Unix timestamp (in seconds) when the character was created.

1338 1334

1339- `VideoModel = string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`1335 - `name: string`

1340 1336

1341 - `string`1337 Display name for the character.

1342 1338

1343 - `"sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`1339### Video Create Error

1344 1340

1345 - `"sora-2"`1341- `VideoCreateError object { code, message }`

1346 1342

1347 - `"sora-2-pro"`1343 An error that occurred while generating the response.

1348 1344

1349 - `"sora-2-2025-10-06"`1345 - `code: string`

1350 1346

1351 - `"sora-2-pro-2025-10-06"`1347 A machine-readable error code that was returned.

1352 1348

1353 - `"sora-2-2025-12-08"`1349 - `message: string`

1354 1350

1355### Video Seconds1351 A human-readable description of the error that was returned.

1356 1352

1357- `VideoSeconds = "4" or "8" or "12"`1353### Video Delete Response

1358 1354

1359 - `"4"`1355- `VideoDeleteResponse object { id, deleted, object }`

1360 1356

1361 - `"8"`1357 Confirmation payload returned after deleting a video.

1362 1358

1363 - `"12"`1359 - `id: string`

1364 1360

1365### Video Size1361 Identifier of the deleted video.

1366 1362

1367- `VideoSize = "720x1280" or "1280x720" or "1024x1792" or "1792x1024"`1363 - `deleted: boolean`

1368 1364

1369 - `"720x1280"`1365 Indicates that the video resource was deleted.

1370 1366

1371 - `"1280x720"`1367 - `object: "video.deleted"`

1372 1368

1373 - `"1024x1792"`1369 The object type that signals the deletion response.

1374 1370

1375 - `"1792x1024"`1371 - `"video.deleted"`

1376 1372

1377### Video Create Character Response1373### Video Get Character Response

1378 1374

1379- `VideoCreateCharacterResponse object { id, created_at, name }`1375- `VideoGetCharacterResponse object { id, created_at, name }`

1380 1376

1381 - `id: string`1377 - `id: string`

1382 1378

1390 1386

1391 Display name for the character.1387 Display name for the character.

1392 1388

1393### Video Get Character Response1389### Video Model

1394 1390

1395- `VideoGetCharacterResponse object { id, created_at, name }`1391- `VideoModel = string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`

1396 1392

1397 - `id: string`1393 - `string`

1398 1394

1399 Identifier for the character creation cameo.1395 - `"sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more`

1400 1396

1401 - `created_at: number`1397 - `"sora-2"`

1402 1398

1403 Unix timestamp (in seconds) when the character was created.1399 - `"sora-2-pro"`

1404 1400

1405 - `name: string`1401 - `"sora-2-2025-10-06"`

1406 1402

1407 Display name for the character.1403 - `"sora-2-pro-2025-10-06"`

1408 1404

1409### Video Delete Response1405 - `"sora-2-2025-12-08"`

1410 1406

1411- `VideoDeleteResponse object { id, deleted, object }`1407### Video Seconds

1412 1408

1413 Confirmation payload returned after deleting a video.1409- `VideoSeconds = "4" or "8" or "12"`

1414 1410

1415 - `id: string`1411 - `"4"`

1416 1412

1417 Identifier of the deleted video.1413 - `"8"`

1418 1414

1419 - `deleted: boolean`1415 - `"12"`

1420 1416

1421 Indicates that the video resource was deleted.1417### Video Size

1422 1418

1423 - `object: "video.deleted"`1419- `VideoSize = "720x1280" or "1280x720" or "1024x1792" or "1792x1024"`

1424 1420

1425 The object type that signals the deletion response.1421 - `"720x1280"`

1426 1422

1427 - `"video.deleted"`1423 - `"1280x720"`

1424

1425 - `"1024x1792"`

1426

1427 - `"1792x1024"`

resources/videos/index.md 2026-07-25 05:59 UTC to 2026-07-29 15:02 UTC

Videos

Create video

Body Parameters

Returns

Example

Response

Example

Response

Create a character from an uploaded video.

Returns

Example

Response

Delete video

Path Parameters

Returns

Example

Response

Retrieve video content

Path Parameters

Query Parameters

Example

Create a new video generation job by editing a source video or existing generated video.

Body Parameters

Returns

Example

Response

Create an extension of a completed video.

Body Parameters

Returns

Example

Response

Fetch a character.

Path Parameters

Returns

Example

Response

List videos

Query Parameters

Returns

Example

Response

Example

Response

Remix video

Path Parameters

Body Parameters

Returns

Example

Response

Example

Response

Retrieve video

Path Parameters

Returns

Example

Response

Domain Types

Image Input Reference Param

Video

Video Create Character Response

Video Create Error

Video Delete Response

Video Get Character Response

Video Model

Video Seconds

Video Size