Create a task

POST /v1/videos

Create an async task here: submit, get a task_id, then poll for the result.

Request body (VideoRequest)

Request example

{
  "model": "gpt-image-2",
  "prompt": "a neon fox, cinematic",
  "seconds": "8",
  "size": "1024x1024",
  "tier": "2k",
  "reference_images": ["https://.../ref.png"]
}

Response (normalized task object)

Field	Type	Required	Description
`model`	`string`	Required	Public model name — see Models
`prompt`	`string`	Required	Text prompt
`seconds`	`string \`	number	Optional	Video duration, accepts "8" or 8 (default 4, range 1–60). Ignored by image models
`size`	`string`	Optional	Pixel size WxH, e.g. 1024x1024 / 1280x720. Aspect ratio is inferred from size — no separate aspect_ratio needed; supported sizes on each model page
`tier`	`string`	Optional	Resolution/quality tier: images 1k/2k/4k, veo video lite/720p/1080p (lite = a lighter 720p tier). Defaults per model
`reference_images`	`string[]`	Optional	Reference images (https URL or base64 data URL). Counts per model page
`metadata`	`object`	Optional	Custom/extension parameter container: top-level fields stay stable, model-specific params go here. Used by omni: metadata.first_last_frame (bool, first/last frame), metadata.source_video_url (string, video-edit source). Pass via extra_body with the OpenAI SDK
Field	Type	Required	Description
`id`	`string`	Always	Public task ID task_xxxx, used to query/download
`task_id`	`string`	Always	Same as id, legacy alias (deprecated)
`object`	`string`	Always	Always "video" (even for image tasks)
`model`	`string`	Always	Public model name
`status`	`string`	Always	queued / in_progress / completed / failed
`progress`	`number`	Always	Progress 0–100
`created_at`	`number`	Always	Created time (Unix seconds)
`completed_at`	`number`	Optional	Completed time, returned only when present
`expires_at`	`number`	Optional	Expiry time, returned only when present
`output_url`	`string`	Optional	Unified download URL, only after completion: {base}/v1/videos/{task_id}/content
`error`	`object`	Optional	{message, code} on failure, omitted otherwise

Response example

{
  "id": "task_xxxxxxxx",
  "task_id": "task_xxxxxxxx",
  "object": "video",
  "model": "gpt-image-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1700000000,
  "seconds": "8",
  "size": "1024x1024"
}