Background texture
ModelMax

视频生成

ModelMax 通过基于队列的 API 提供异步视频生成。你提交一个提示词，轮询状态，然后下载结果。

这与对话补全不同 — 视频生成可能需要几分钟，因此使用提交-轮询模式而非同步响应。

工作流概览

1. 提交    POST /v1/queue/{model}           → 202 + request_id
2. 轮询    GET  .../requests/{id}/status    → IN_QUEUE | IN_PROGRESS | COMPLETED | FAILED
3. 结果    GET  .../requests/{id}           → 数据 URL + 用量
4. 下载    GET  .../requests/{id}/content/0 → video/mp4 二进制

步骤 1：提交任务

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 golden retriever running through autumn leaves in slow motion"
  }'

import requests

API_KEY = "your-api-key"
BASE_URL = "https://api.modelmax.io"

resp = requests.post(
    f"{BASE_URL}/v1/queue/veo-3",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"prompt": "A golden retriever running through autumn leaves in slow motion"},
)
resp.raise_for_status()
task = resp.json()

print(f"Request ID: {task['request_id']}")
print(f"Status URL: {task['status_url']}")

const BASE_URL = "https://api.modelmax.io";
const API_KEY = "your-api-key";

const resp = await fetch(`${BASE_URL}/v1/queue/veo-3`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    prompt: "A golden retriever running through autumn leaves in slow motion",
  }),
});

const task = await resp.json();
console.log("Request ID:", task.request_id);

响应（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..."
}

保存提交响应中的 status_url 和 response_url — 它们包含了轮询所需的完整路径。

步骤 2：轮询状态

状态端点是轻量级的，不会触发计费。建议每 5 秒轮询一次。

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

import time

while True:
    status_resp = requests.get(
        f"{BASE_URL}{task['status_url']}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    status = 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 status: string;
do {
  await sleep(5000);
  const statusResp = await fetch(`${BASE_URL}${task.status_url}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const statusData = await statusResp.json();
  status = statusData.status;
  console.log("Status:", status);
} while (status !== "COMPLETED" && status !== "FAILED");

状态值

状态描述
IN_QUEUE任务已接受，等待开始
IN_PROGRESS视频正在生成中
COMPLETED视频已准备好下载
FAILED生成失败（检查 error 字段）

步骤 3：获取结果

当状态为 COMPLETED 时，获取完整结果以取得下载 URL。此操作会触发计费。

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

result_resp = requests.get(
    f"{BASE_URL}{task['response_url']}",
    headers={"Authorization": f"Bearer {API_KEY}"},
)
result = result_resp.json()

if result["status"] == "COMPLETED":
    for i, video in enumerate(result["data"]):
        print(f"Video {i}: {video['url']}")

const resultResp = await fetch(`${BASE_URL}${task.response_url}`, {
  headers: { Authorization: `Bearer ${API_KEY}` },
});
const result = await resultResp.json();

if (result.status === "COMPLETED") {
  for (const video of result.data) {
    console.log("Download:", video.url);
  }
}

步骤 4：下载视频

每个数据条目中的 url 是相对路径。请求该路径以下载 MP4 二进制文件。

curl -o video.mp4 \
  https://api.modelmax.io/v1/queue/veo-3/requests/{content_id}/content/0 \
  -H "Authorization: Bearer $MODELMAX_API_KEY"

for i, video in enumerate(result["data"]):
    video_resp = requests.get(
        f"{BASE_URL}{video['url']}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    with open(f"video_{i}.mp4", "wb") as f:
        f.write(video_resp.content)
    print(f"Saved video_{i}.mp4")

import { writeFile } from "fs/promises";

for (let i = 0; i < result.data.length; i++) {
  const videoResp = await fetch(`${BASE_URL}${result.data[i].url}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  const buffer = Buffer.from(await videoResp.arrayBuffer());
  await writeFile(`video_${i}.mp4`, buffer);
  console.log(`Saved video_${i}.mp4`);
}

完整示例

以下是一个完整的端到端流程脚本：

import requests
import time

API_KEY = "your-api-key"
BASE = "https://api.modelmax.io"

# 1. 提交
task = requests.post(
    f"{BASE}/v1/queue/veo-3",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"prompt": "Timelapse of a flower blooming in a garden"},
).json()
print(f"Submitted: {task['request_id']}")

# 2. 轮询
while True:
    time.sleep(5)
    status = requests.get(
        f"{BASE}{task['status_url']}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    ).json()
    print(f"  Status: {status['status']}")
    if status["status"] in ("COMPLETED", "FAILED"):
        break

# 3. 结果
result = requests.get(
    f"{BASE}{task['response_url']}",
    headers={"Authorization": f"Bearer {API_KEY}"},
).json()

# 4. 下载
if result["status"] == "COMPLETED":
    for i, v in enumerate(result["data"]):
        data = requests.get(
            f"{BASE}{v['url']}", headers={"Authorization": f"Bearer {API_KEY}"}
        ).content
        with open(f"video_{i}.mp4", "wb") as f:
            f.write(data)
        print(f"Saved video_{i}.mp4 ({len(data)} bytes)")
else:
    print(f"Failed: {result.get('error', 'unknown error')}")

可选参数

传递 parameters 对象来控制生成选项：

{
  "prompt": "A drone shot of ocean waves",
  "parameters": {
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration_seconds": 6,
    "generate_audio": true,
    "negative_prompt": "blurry, low quality"
  }
}
参数类型默认值描述
aspect_ratiostring"16:9""16:9" 或 "9:16"
resolutionstring"720p""720p"、"1080p" 或 "4k"
duration_secondsinteger8视频时长，最大 8 秒
generate_audiobooleantrue包含音频轨道
sample_countinteger1生成视频数量（1–4）
negative_promptstring—需要避免的内容
imagestring—用于图生视频的 Base64 图像

可用模型

模型速度质量
veo-3.1标准最高
veo-3.1-fast快速高
veo-3标准高
veo-3-fast快速良好
veo-2标准良好