Unified media API

Create a task

POST/v1/videos

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

Request body (VideoRequest)

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 720p/1080p/4k. 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

Request example

json

{
  "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
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

json

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