POST /v1/queue/{model}

POST/v1/queue/{model}

提交异步视频生成任务。立即返回请求 ID 和轮询 URL。

请求

路径参数

参数	类型	描述
`model`	`string`	视频模型 ID（如 `veo-3`、`veo-3-fast`）。

请求头

请求头	值
`Authorization`	`Bearer {api_key}`
`Content-Type`	`application/json`

请求体

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

参数

参数	类型	必填	描述
`prompt`	`string`	是	视频的文本描述。
`parameters`	`object`	否	生成选项（见下文）。

parameters 对象

字段	类型	默认值	描述
`aspect_ratio`	`string`	`"16:9"`	`"16:9"` 或 `"9:16"`
`resolution`	`string`	`"720p"`	`"720p"`、`"1080p"` 或 `"4k"`
`duration_seconds`	`integer`	`8`	时长（秒），最大 8
`generate_audio`	`boolean`	`true`	包含音频轨道
`sample_count`	`integer`	`1`	生成视频数量（1–4）
`negative_prompt`	`string`	—	需要避免的内容
`image`	`string`	—	用于图生视频的 Base64 图像

响应

状态码：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..."
}

字段	类型	描述
`request_id`	`string`	唯一任务标识符。
`status`	`string`	提交时始终为 `"IN_QUEUE"`。
`status_url`	`string`	用于状态检查的相对 URL。
`response_url`	`string`	用于完整结果的相对 URL。

状态码

状态码	描述
`202`	任务已接受
`400`	无效请求、缺少 prompt 或非视频模型
`401`	未授权
`402`	余额不足
`502`	上游供应商错误

示例

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);

下一步

轮询任务状态 → 队列状态