動画生成

ModelMax はキューベース API による非同期動画生成を提供します。プロンプトを送信し、ステータスをポーリングしてから、結果をダウンロードします。

これはチャット補完とは異なります。動画生成には数分かかることがあるため、同期レスポンスではなく submit-and-poll パターンを使用します。

ワークフロー概要

1. Submit    POST /v1/queue/{model}           → 202 + request_id
2. Poll      GET  .../requests/{id}/status    → IN_QUEUE | IN_PROGRESS | COMPLETED | FAILED
3. Result    GET  .../requests/{id}           → data URLs + usage
4. Download  GET  .../requests/{id}/content/0 → video/mp4 binary

Step 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 を保存してください。ポーリングに必要な完全なパスが含まれています。

Step 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` フィールドを確認）

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

Step 4: 動画をダウンロードする

各 data エントリの 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`);
}

完全な例

エンドツーエンドの流れを 1 つのスクリプトにまとめると次のようになります。

import requests
import time

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

# 1. Submit
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. Poll
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
result = requests.get(
    f"{BASE}{task['response_url']}",
    headers={"Authorization": f"Bearer {API_KEY}"},
).json()

# 4. Download
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_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`	—	image-to-video 用の Base64 画像

利用可能なモデル

モデル	速度	品質
`veo-3.1`	標準	最高
`veo-3.1-fast`	高速	高
`veo-3`	標準	高
`veo-3-fast`	高速	良
`veo-2`	標準	良