OpenAI API (unofficial showcase)
POST/videosDeprecated

Create a video

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

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

5 body fields
modelstringoptional
The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to `sora-2`.
promptstringrequired
Text prompt that describes the video to generate.
input_referenceobjectoptional
Optional reference object that guides generation. Provide exactly one of `image_url` or `file_id`.
secondsstringoptional
Clip duration in seconds (allowed values: 4, 8, 12). Defaults to 4 seconds.
Allowed:4812
sizestringoptional
Output resolution formatted as width x height (allowed values: 720x1280, 1280x720, 1024x1792, 1792x1024). Defaults to 720x1280.
Allowed:720x12801280x7201024x17921792x1024

6 status codes
200Success
idstringrequired
Unique identifier for the video job.
objectstringrequired
The object type, which is always `video`.
Allowed:videoDefault:video
modelstringrequired
The video generation model that produced the job.
statusstringrequired
Current lifecycle status of the video job.
Allowed:queuedin_progresscompletedfailed
progressintegerrequired
Approximate completion percentage for the generation task.
created_atintegerrequired
Unix timestamp (seconds) for when the job was created.
completed_atintegerrequired
Unix timestamp (seconds) for when the job completed, if finished.
expires_atintegerrequired
Unix timestamp (seconds) for when the downloadable assets expire, if set.
promptstringrequired
The prompt that was used to generate the video.
sizestringrequired
The resolution of the generated video.
Allowed:720x12801280x7201024x17921792x1024
secondsstringrequired
Duration of the generated clip in seconds. For extensions, this is the stitched total duration.
remixed_from_video_idstringrequired
Identifier of the source video if this video is a remix.
errorobjectrequired
Error payload that explains why generation failed, if applicable.
400The video request is invalid, or the organization does not support video generation.
errorobjectrequired
404A referenced character was not found or is not accessible, or the Videos API is unavailable.
errorobjectrequired
429The request was rejected because a rate limit was exceeded. A slow_down error means traffic increased too quickly; reduce your request rate, then increase it gradually.

One documented failure

  • slow_down

    Your request rate increased too quickly. Please reduce the request rate and gradually increase it again.

    Traffic increased too quickly

errorobjectrequired
500The video generation task could not be created.
errorobjectrequired
503The service is temporarily unavailable. A server_is_overloaded error means the requested model is temporarily overloaded; retry after a brief delay.

One documented failure

  • server_is_overloaded

    The model is temporarily overloaded. Please retry your request after a brief delay.

    The requested model is temporarily overloaded

errorobjectrequired

Error handling

A 400 is returned: The video request is invalid, or the organization does not support video generation. A 404 is returned: A referenced character was not found or is not accessible, or the Videos API is unavailable. A 429 is returned: The request was rejected because a rate limit was exceeded. A slow_down error means traffic increased too quickly; reduce your request rate, then increase it gradually. A 500 is returned: The video generation task could not be created. A 503 is returned: The service is temporarily unavailable. A server_is_overloaded error means the requested model is temporarily overloaded; retry after a brief delay.