# Videos ## Create video `$ openai videos create` **post** `/videos` Create a new video generation job from a prompt and optional reference assets. ### Parameters - `--prompt: string` Text prompt that describes the video to generate. - `--input-reference: optional string or ImageInputReferenceParam` Optional reference asset upload or reference object that guides generation. - `--model: optional string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more` The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to `sora-2`. - `--seconds: optional "4" or "8" or "12"` Clip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds. - `--size: optional "720x1280" or "1280x720" or "1024x1792" or "1792x1024"` Output resolution formatted as width x height (allowed values: 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280. ### 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: object { code, message }` 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: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more` The video generation model that produced the job. - `"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`. - `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 or VideoSeconds` Duration of the generated clip in seconds. For extensions, this is the stitched total duration. - `"4"` - `"8"` - `"12"` - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"` 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 ```cli openai videos create \ --api-key 'My API Key' \ --prompt x ``` #### Response ```json { "id": "id", "completed_at": 0, "created_at": 0, "error": { "code": "code", "message": "message" }, "expires_at": 0, "model": "string", "object": "video", "progress": 0, "prompt": "prompt", "remixed_from_video_id": "remixed_from_video_id", "seconds": "string", "size": "720x1280", "status": "queued" } ``` ## Create a new video generation job by editing a source video or existing generated video. `$ openai videos edit` **post** `/videos/edits` Create a new video generation job by editing a source video or existing generated video. ### Parameters - `--prompt: string` Text prompt that describes how to edit the source video. - `--video: string or object { id }` Reference to the completed video to edit. ### 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: object { code, message }` 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: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more` The video generation model that produced the job. - `"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`. - `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 or VideoSeconds` Duration of the generated clip in seconds. For extensions, this is the stitched total duration. - `"4"` - `"8"` - `"12"` - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"` 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 ```cli openai videos edit \ --api-key 'My API Key' \ --prompt x \ --video 'Example data' ``` #### Response ```json { "id": "id", "completed_at": 0, "created_at": 0, "error": { "code": "code", "message": "message" }, "expires_at": 0, "model": "string", "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. `$ openai videos extend` **post** `/videos/extensions` Create an extension of a completed video. ### Parameters - `--prompt: string` Updated text prompt that directs the extension generation. - `--seconds: "4" or "8" or "12"` Length of the newly generated extension segment in seconds (allowed values: 4, 8, 12, 16, 20). - `--video: string or object { id }` Reference to the completed video to extend. ### 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: object { code, message }` 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: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more` The video generation model that produced the job. - `"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`. - `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 or VideoSeconds` Duration of the generated clip in seconds. For extensions, this is the stitched total duration. - `"4"` - `"8"` - `"12"` - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"` 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 ```cli openai videos extend \ --api-key 'My API Key' \ --prompt x \ --seconds 4 \ --video 'Example data' ``` #### Response ```json { "id": "id", "completed_at": 0, "created_at": 0, "error": { "code": "code", "message": "message" }, "expires_at": 0, "model": "string", "object": "video", "progress": 0, "prompt": "prompt", "remixed_from_video_id": "remixed_from_video_id", "seconds": "string", "size": "720x1280", "status": "queued" } ``` ## Create a character from an uploaded video. `$ openai videos create-character` **post** `/videos/characters` Create a character from an uploaded video. ### Parameters - `--name: string` Display name for this API character. - `--video: string` Video file used to create a character. ### Returns - `VideoNewCharacterResponse: 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. ### Example ```cli openai videos create-character \ --api-key 'My API Key' \ --name x \ --video 'Example data' ``` #### Response ```json { "id": "id", "created_at": 0, "name": "name" } ``` ## Fetch a character. `$ openai videos get-character` **get** `/videos/characters/{character_id}` Fetch a character. ### Parameters - `--character-id: string` The identifier of the character to retrieve. ### Returns - `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. ### Example ```cli openai videos get-character \ --api-key 'My API Key' \ --character-id char_123 ``` #### Response ```json { "id": "id", "created_at": 0, "name": "name" } ``` ## List videos `$ openai videos list` **get** `/videos` List recently generated videos for the current project. ### 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. ### Returns - `VideoListResource: object { data, first_id, has_more, 2 more }` - `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: object { code, message }` 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: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more` The video generation model that produced the job. - `"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`. - `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 or VideoSeconds` Duration of the generated clip in seconds. For extensions, this is the stitched total duration. - `"4"` - `"8"` - `"12"` - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"` 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`. ### Example ```cli openai videos list \ --api-key 'My API Key' ``` #### Response ```json { "data": [ { "id": "id", "completed_at": 0, "created_at": 0, "error": { "code": "code", "message": "message" }, "expires_at": 0, "model": "string", "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" } ``` ## Retrieve video `$ openai videos retrieve` **get** `/videos/{video_id}` Fetch the latest metadata for a generated video. ### Parameters - `--video-id: string` The identifier of the video to retrieve. ### 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: object { code, message }` 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: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more` The video generation model that produced the job. - `"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`. - `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 or VideoSeconds` Duration of the generated clip in seconds. For extensions, this is the stitched total duration. - `"4"` - `"8"` - `"12"` - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"` 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 ```cli openai videos retrieve \ --api-key 'My API Key' \ --video-id video_123 ``` #### Response ```json { "id": "id", "completed_at": 0, "created_at": 0, "error": { "code": "code", "message": "message" }, "expires_at": 0, "model": "string", "object": "video", "progress": 0, "prompt": "prompt", "remixed_from_video_id": "remixed_from_video_id", "seconds": "string", "size": "720x1280", "status": "queued" } ``` ## Delete video `$ openai videos delete` **delete** `/videos/{video_id}` Permanently delete a completed or failed video and its stored assets. ### Parameters - `--video-id: string` The identifier of the video to delete. ### Returns - `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. ### Example ```cli openai videos delete \ --api-key 'My API Key' \ --video-id video_123 ``` #### Response ```json { "id": "id", "deleted": true, "object": "video.deleted" } ``` ## Remix video `$ openai videos remix` **post** `/videos/{video_id}/remix` Create a remix of a completed video using a refreshed prompt. ### Parameters - `--video-id: string` The identifier of the completed video to remix. - `--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: object { code, message }` 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: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more` The video generation model that produced the job. - `"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`. - `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 or VideoSeconds` Duration of the generated clip in seconds. For extensions, this is the stitched total duration. - `"4"` - `"8"` - `"12"` - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"` 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 ```cli openai videos remix \ --api-key 'My API Key' \ --video-id video_123 \ --prompt x ``` #### Response ```json { "id": "id", "completed_at": 0, "created_at": 0, "error": { "code": "code", "message": "message" }, "expires_at": 0, "model": "string", "object": "video", "progress": 0, "prompt": "prompt", "remixed_from_video_id": "remixed_from_video_id", "seconds": "string", "size": "720x1280", "status": "queued" } ``` ## Retrieve video content `$ openai videos download-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. ### Parameters - `--video-id: string` The identifier of the video whose media to download. - `--variant: optional "video" or "thumbnail" or "spritesheet"` Which downloadable asset to return. Defaults to the MP4 video. ### Returns - `unnamed_schema_6: file path` ### Example ```cli openai videos download-content \ --api-key 'My API Key' \ --video-id video_123 ``` ## Domain Types ### Image Input Reference Param - `image_input_reference_param: 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: object { code, message }` 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: string or "sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more` The video generation model that produced the job. - `"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`. - `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 or VideoSeconds` Duration of the generated clip in seconds. For extensions, this is the stitched total duration. - `"4"` - `"8"` - `"12"` - `size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"` 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 Error - `video_create_error: 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 Seconds - `video_seconds: "4" or "8" or "12"` - `"4"` - `"8"` - `"12"` ### Video Size - `video_size: "720x1280" or "1280x720" or "1024x1792" or "1792x1024"` - `"720x1280"` - `"1280x720"` - `"1024x1792"` - `"1792x1024"`