POST /v1/queue/{model}

POST/v1/queue/{model}

Submits an async video generation task. Returns immediately with a request ID and polling URLs.

Request

Path parameters

Parameter	Type	Description
`model`	`string`	Video model ID (e.g. `veo-3`, `veo-3-fast`).

Headers

Header	Value
`Authorization`	`Bearer {api_key}`
`Content-Type`	`application/json`

Body

{
  "prompt": "A drone shot flying over a coral reef at sunset",
  "parameters": {
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration_seconds": 8,
    "generate_audio": true
  }
}

Parameters

Parameter	Type	Required	Description
`prompt`	`string`	Yes	Text description of the video.
`parameters`	`object`	No	Generation options (see below).

Parameters object

Field	Type	Default	Description
`aspect_ratio`	`string`	`"16:9"`	`"16:9"` or `"9:16"`
`resolution`	`string`	`"720p"`	`"720p"`, `"1080p"`, or `"4k"`
`duration_seconds`	`integer`	`8`	Duration in seconds, max 8
`generate_audio`	`boolean`	`true`	Include audio track
`sample_count`	`integer`	`1`	Number of videos (1–4)
`negative_prompt`	`string`	—	What to avoid
`image`	`string`	—	Base64 image for image-to-video

Response

Status: 202 Accepted

{
  "request_id": "Z2VtaW5pOnZlby0zOjg6NzIwcDoxOm9wLTEyMzQ1",
  "status": "IN_QUEUE",
  "status_url": "/v1/queue/veo-3/requests/Z2Vt.../status",
  "response_url": "/v1/queue/veo-3/requests/Z2Vt..."
}

Field	Type	Description
`request_id`	`string`	Unique task identifier.
`status`	`string`	Always `"IN_QUEUE"` on submit.
`status_url`	`string`	Relative URL for status checks.
`response_url`	`string`	Relative URL for full results.

Status codes

Status	Description
`202`	Task accepted
`400`	Invalid request, missing prompt, or not a video model
`401`	Unauthorized
`402`	Insufficient balance
`502`	Upstream provider error

Examples

curl -X POST https://api.modelmax.io/v1/queue/veo-3 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MODELMAX_API_KEY" \
  -d '{
    "prompt": "A cat playing piano in a jazz club"
  }'

import requests

resp = requests.post(
    "https://api.modelmax.io/v1/queue/veo-3",
    headers={"Authorization": "Bearer your-key"},
    json={"prompt": "A cat playing piano in a jazz club"},
)
task = resp.json()
print(task["request_id"])

const resp = await fetch("https://api.modelmax.io/v1/queue/veo-3", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer your-key",
  },
  body: JSON.stringify({ prompt: "A cat playing piano in a jazz club" }),
});
const task = await resp.json();
console.log(task.request_id);

Next step

Poll the task status → Queue Status