Videos · API reference

Videos

Submit a generation job, check its status, and fetch the result.

All requests need Authorization: Bearer tf_…; see Authentication. Bodies are JSON. Errors use the same envelope as the chat API: { "error": { "message", "type", "code" } }.

Submit a job

POST /v1/videos

Field	Type	Description
`model`	string, required	A routable model, for example `minimax/h3`. List them with `GET /v1/models`.
`task`	string, required	`t2va`, `fl2va`, or `ref2va`. See Tasks and inputs.
`prompt`	string	Required for `t2va`; optional for `fl2va` and `ref2va`.
`seconds`	integer, 4 to 15	Length of the clip.
`target`	object	`{ "short_edge": 768, "aspect_ratio": "16:9" }`. Only 768 is accepted for `short_edge`. The set of supported aspect ratios is not final.
`quality`	string	`lossless` or `turbo` at launch. See Quality and output.
`conditions`	array	Required for `fl2va` (1 or 2 frames) and `ref2va`. Entry shape depends on the task.
`num_outputs_per_prompt`	integer, 1 to 10	Number of takes. Fetch each by variant.
`seed`	integer	Starting noise, for repeatable runs.

Returns 201. The request is validated first; nothing is queued if it is invalid. Defaults for fields you omit are not final.

201 Created

{
  "id": "vid_9f2a...",
  "status": "queued",
  "model": "minimax/h3",
  "created_at": "2026-10-17T18:04:02Z",
  "eta_seconds": 60
}

Get a job

GET /v1/videos/{id}

200 OK

{
  "id": "vid_9f2a...",
  "status": "processing",
  "progress": null,
  "created_at": "2026-10-17T18:04:02Z",
  "started_at": "2026-10-17T18:04:20Z",
  "completed_at": null
}

Field	Description
`status`	`queued` · `processing` · `completed` · `failed` · `canceled`. See Jobs.
`progress`	Always `null`. There is no mid-generation progress.
`created_at`	When the job was accepted.
`started_at`	When a worker claimed it; null while queued.
`completed_at`	When it finished; null until then.

Download a result

GET /v1/videos/{id}/content?variant=0

302 to a short-lived signed URL for the MP4. 404 if the job is not completed. variant picks among the outputs when num_outputs_per_prompt was more than 1; it defaults to the first.

List models

GET /v1/models

Lists the model values that are routable right now, so a client does not need to hard-code availability. A model that is documented but not yet live is reported as not yet available, not as a generic 404.

Errors

type	When
`authentication_error`	Missing or revoked key (`code: invalid_api_key`, HTTP 401).
`invalid_request_error`	Unknown `model` or `task`; `seconds` or `num_outputs_per_prompt` out of range; missing `prompt` for `t2va`; missing or malformed `conditions`. Rejected before queueing (HTTP 400).
`content_policy_violation`	The prompt or an input was rejected by moderation. No GPU time was used.
`api_error`	A server-side failure.

A note on status codes

400 and 401 follow the chat API. The HTTP status for content_policy_violation is not specified yet; branch on error.type, not on the status.

← Quality and output Model catalog →