GET /v1/queue/{model}/requests/{requestID}/status

GET/v1/queue/{model}/requests/{requestID}/status

Lightweight status check for a video generation task. Does not trigger billing. Use this endpoint for polling.

Request

Path parameters

Parameter	Type	Description
`model`	`string`	Video model ID (e.g. `veo-3`).
`requestID`	`string`	Request ID from the submit response.

Headers

Header	Value
`Authorization`	`Bearer {api_key}`

Response

{
  "request_id": "Z2VtaW5pOnZlby0zOjg6NzIwcDoxOm9wLTEyMzQ1",
  "status": "IN_PROGRESS"
}

Field	Type	Description
`request_id`	`string`	The request ID.
`status`	`string`	Current task status.
`error`	`string`	Error message (only when `FAILED`).

Status values

Status	Description
`IN_QUEUE`	Task accepted, waiting to be processed
`IN_PROGRESS`	Video is actively being generated
`COMPLETED`	Generation finished — fetch the full result
`FAILED`	Generation failed — check the `error` field

This endpoint only returns status metadata. To get video download URLs and trigger billing, use the Queue Result endpoint once status is COMPLETED.

Status codes

Status	Description
`200`	Success
`400`	Invalid request ID
`401`	Unauthorized
`502`	Upstream provider error

Examples

curl https://api.modelmax.io/v1/queue/veo-3/requests/{request_id}/status \
  -H "Authorization: Bearer $MODELMAX_API_KEY"

import time
import requests

BASE = "https://api.modelmax.io"
headers = {"Authorization": "Bearer your-key"}

while True:
    resp = requests.get(f"{BASE}{task['status_url']}", headers=headers)
    status = resp.json()
    print(f"Status: {status['status']}")

    if status["status"] in ("COMPLETED", "FAILED"):
        break
    time.sleep(5)

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

let done = false;
while (!done) {
  await sleep(5000);
  const resp = await fetch(`${BASE_URL}${task.status_url}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const status = await resp.json();
  console.log("Status:", status.status);
  done = status.status === "COMPLETED" || status.status === "FAILED";
}

Next step

When status is COMPLETED → Queue Result