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`	—	image-to-video 用の 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);

次のステップ

タスクステータスをポーリングする → キュー状態