Video generation

POST/v1/videos/generations

Create asynchronous video tasks, then retrieve, list, or cancel them.

Video generation is asynchronous. After creation returns a task object, poll by task ID until the status is succeeded, failed, or canceled.

Read the complete video guide for text/image input, backoff polling, and downloads

Create task fields

Field	Type	Required	Description
`model`	string	Yes	A video model ID returned by /v1/models.
`prompt`	string	No	Conditional: A text prompt; required when no reference image is provided.
`image_url`	string	No	Conditional: A reference image URL that can satisfy the input requirement without prompt.
`image_urls`	string[]	No	Conditional: Multiple reference image URLs when supported by the model.
`negative_prompt`	string	No	A negative prompt when supported by the model.
`video_url`	string	No	A reference video URL when supported by the model.
`audio_url`	string	No	A reference audio URL supported by only some video models.
`media`	object[]	No	Unified media inputs with type, url, and optional role.
`duration`	integer	No	Requested duration; accepted values and pricing tiers follow model configuration.
`ratio`	string	No	Requested aspect ratio; accepted values depend on the model.
`resolution`	string	No	Requested resolution; accepted values depend on the model.
`prompt_extend`	boolean	No	Requests prompt expansion when supported by the model.
`generate_audio`	boolean	No	Requests generated audio when supported by the model.
`watermark`	boolean	No	Requests a watermark when supported by the Provider.
`seed`	integer	No	A random seed when supported by the Provider.
`metadata`	object	No	Caller-defined metadata.

Create a task

Creation returns a task ID, status, and creation time. Some Providers may return a terminal state immediately; always follow the status field.

curl https://api.noxgate.net/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","prompt":"A paper airplane crossing a sunlit room","duration":5}'

{
  "id": "video_task_example",
  "object": "video.generation",
  "model": "YOUR_MODEL_ID",
  "status": "processing",
  "created": 1750000000
}

Retrieve a task

GET/v1/videos/generations/:task_id

Retrieve the latest state by task ID. model can be omitted for a task already recorded by the platform; when supplied, the gateway resolves that model route.

curl "https://api.noxgate.net/v1/videos/generations/video_task_example" \
  -H "Authorization: Bearer sk-your-api-key"

{
  "id": "video_task_example",
  "object": "video.generation",
  "model": "YOUR_MODEL_ID",
  "status": "succeeded",
  "created": 1750000000,
  "result": { "url": "https://provider.example/generated-video.mp4", "duration": 5 }
}

List tasks

GET/v1/videos/generations

The list endpoint requires a model query parameter and accepts optional limit, after, and status filters.

curl "https://api.noxgate.net/v1/videos/generations?model=YOUR_MODEL_ID&limit=20&status=processing" \
  -H "Authorization: Bearer sk-your-api-key"

Cancel a task

DELETE/v1/videos/generations/:task_id

A successful cancellation returns 204 No Content. model can be omitted for a recorded task; cancellation availability depends on its current Provider state.

curl -X DELETE "https://api.noxgate.net/v1/videos/generations/video_task_example" \
  -H "Authorization: Bearer sk-your-api-key"

Task lifecycle

Create the task and retain the id from the response.
Poll the retrieve endpoint; names for non-terminal states can vary by Provider.
succeeded exposes result.url, failed carries error details, and canceled indicates cancellation.
Do not assume a fixed polling interval, processing time, or result URL lifetime.