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

Create a video

POST
/videos

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

Body Parameters
JSON
prompt: string

Text prompt that describes the video to generate.

minLength1
maxLength32000
input_reference: optional ImageInputReferenceParam { file_id, image_url }

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.

maxLength20971520
formaturi
model: optional VideoModel

The video generation model to use (allowed values: sora-2, sora-2-pro). Defaults to sora-2.

One of the following:
string
"sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more
One of the following:
"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.

One of the following:
"4"
"8"
"12"
size: optional VideoSize

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

One of the following:
"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 or null

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

formatunixtime
created_at: number

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

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

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.

headers: optional map[string]

The Retry-After and Retry-After-Ms headers returned with the original error, if any.

misalignment: optional object { detailed_explanation, error_type, review_target, steer }
detailed_explanation: optional string

The public explanation for this block.

error_type: optional string or "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

An optional classification; clients must accept additional values.

One of the following:
string
SafetyAlertErrorType = "potentially_unintended_data_transfer" or "potentially_unintended_data_access" or "potentially_unintended_destructive_activity" or "other"

An optional classification; clients must accept additional values.

One of the following:
"potentially_unintended_data_transfer"
"potentially_unintended_data_access"
"potentially_unintended_destructive_activity"
"other"
review_target: optional string or null

An opaque target for explicitly continuing this review, or null when unavailable.

minLength1
maxLength96
steer: optional object { message }

An optional public continuation instruction.

message: string

The public continuation instruction.

param: optional string or null

The request parameter associated with the error, or null if none was recorded.

type: optional string or null

The original error type, or null if it was not recorded.

expires_at: number or null

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

formatunixtime
model: VideoModel

The video generation model that produced the job.

One of the following:
string
"sora-2" or "sora-2-pro" or "sora-2-2025-10-06" or 2 more
One of the following:
"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 or null

The prompt that was used to generate the video.

remixed_from_video_id: string or null

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.

One of the following:
"720x1280"
"1280x720"
"1024x1792"
"1792x1024"
status: "queued" or "in_progress" or "completed" or "failed"

Current lifecycle status of the video job.

One of the following:
"queued"
"in_progress"
"completed"
"failed"

Create a video

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

{
  "id": "video_123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "size": "1024x1792",
  "seconds": "8",
  "prompt": "A calico cat playing a piano on stage",
  "completed_at": null,
  "expires_at": null,
  "error": null,
  "remixed_from_video_id": null
}
Returns Examples
{
  "id": "video_123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1712697600,
  "size": "1024x1792",
  "seconds": "8",
  "prompt": "A calico cat playing a piano on stage",
  "completed_at": null,
  "expires_at": null,
  "error": null,
  "remixed_from_video_id": null
}