MiniMax H3 video generation

Generate videos with the MiniMax H3 models: text to video, first-and-last-frame image to video, and omni-reference video from reference images, reference videos and reference audio. Besides regular video generation, minimax/minimax-h3 offers two endpoints that only it supports: video upscaling (POST /v1/videos/regenerations, which regenerates a 768P video at 2K) and context enhancement (POST /v1/videos/context, whose result is an enhanced prompt in text). All three kinds of task run asynchronously and are tracked with the same query endpoint. The endpoints follow the shape of OpenAI's Videos API, and the gateway converts the common parameters into MiniMax's format. For the task lifecycle in general, see Asynchronous tasks.

Supported models

minimax/minimax-h3-max has been taken offline by the provider: calling it now returns HTTP 200, but the task object is empty and has no task ID, so it cannot be polled; you are not charged. Use minimax/minimax-h3 instead.

A model must be enabled in the workspace's model marketplace before you can call it; the model marketplace shows the current prices.

Endpoints

The full URL is https://api.lyrouter.com followed by the path in the table. The three submit endpoints share the same model name and the same task IDs, and every task they return is queried with GET /v1/videos/{id}.

Authentication

Send your API key in a request header:

Authorization: Bearer <API Key>

Bearer is case-sensitive. You can use x-api-key: <API Key> instead; when both are present, only Authorization is read. Create API keys on the workspace's API Keys page. Your API key is used only to authenticate with LYRouter and is never forwarded to the upstream provider. See Base URLs and authentication.

Any API key in the same workspace can query and download that workspace's tasks; a key from another workspace gets 404.

Headers

Submit a task

Submits a video generation task. The gateway validates the parameters, converts them into MiniMax's format and submits the task to the provider, then returns a task object with status queued right away; the video is generated in the background. The submit request itself incurs no cost.

Request body

• Image to video and omni reference are mutually exclusive: once you send reference_image, input_reference or reference_audio, you cannot also send first_frame / last_frame, and vice versa. The provider enforces this.
• These parameters exist in the gateway contract (other models use them), but MiniMax has no equivalent, so sending one returns 400 <parameter name> is not supported for this model: generate_audio (sound comes from reference audio), output_format (no container choice), omni_reference_task_type (no omni task types), source_video (belongs to the upscaling endpoint only).
• Other fields not in the table are dropped, and the X-Gateway-Unsupported-Parameters response header lists their names; with X-Gateway-Strict-Parameters: true, the request returns 400 instead. This includes MiniMax's native duration, resolution, ratio and content; use seconds, size and the material fields above instead.
• This endpoint does not support n; each request generates one video.

Submitting a form

POST /v1/videos also accepts multipart/form-data, which is what the official OpenAI SDK's videos.create() uses. In a form, the gateway reads fields such as model, prompt, seconds, size, input_reference and watermark:

• input_reference accepts only a URL; an uploaded file raises no error but is ignored: pass a publicly reachable https:// URL. Currently, when you upload a file, the task is generated as if there were no reference video and is charged as usual.
• watermark accepts only the literal values true or false.
• Submit first_frame, last_frame, reference_image and reference_audio in a JSON request body. Currently these fields in a form are replaced with a placeholder value and forwarded to the provider; with reference_audio, for example, the submission returns 200 and the task then fails with the error.message content[1].audio_url: invalid param: audio url must be http(s):// or data:...;base64 (failed tasks are not charged).

Request examples

The examples read the API key from the LYROUTER_API_KEY environment variable; to set it, see Your first model call.

curl https://api.lyrouter.com/v1/videos \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/minimax-h3",
    "prompt": "Epic space-opera trailer: a female captain alone at the observation window",
    "size": "768P",
    "seconds": 5
  }'

import os
import httpx

resp = httpx.post(
    "https://api.lyrouter.com/v1/videos",
    headers={"Authorization": f"Bearer {os.environ['LYROUTER_API_KEY']}"},
    json={
        "model": "minimax/minimax-h3",
        "prompt": "Epic space-opera trailer: a female captain alone at the observation window",
        "size": "768P",
        "seconds": 5,
    },
    timeout=60,
)
resp.raise_for_status()
dropped = resp.headers.get("X-Gateway-Unsupported-Parameters")
if dropped:
    print("These parameters did not take effect:", dropped)
task = resp.json()
print(task["id"], task["status"])

const resp = await fetch("https://api.lyrouter.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "minimax/minimax-h3",
    prompt: "Epic space-opera trailer: a female captain alone at the observation window",
    size: "768P",
    seconds: 5,
  }),
});
if (!resp.ok) throw new Error(await resp.text());
const dropped = resp.headers.get("X-Gateway-Unsupported-Parameters");
if (dropped) console.log("These parameters did not take effect:", dropped);
const task = await resp.json();
console.log(task.id, task.status);

Response

A successful submission returns HTTP 200 and a task object with status queued; for the fields, see "Retrieve a task" below. The submit response has no usage, because the cost is settled when the task completes. Below, the 400 is a size of 1280x720 (a short edge of 720 is not one of MiniMax's tiers), the 403 is a model that is not enabled in this workspace (or a virtual model or lyrouter/auto), and the 429 means the provider account has reached its limit of concurrent tasks.

{
  "id": "aigwt_minimax_videos_Qm3Tz8VbN1sLk0pYc4dReA",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0,
  "created_at": 1791950400,
  "expires_at": 1792555200,
  "seconds": 5,
  "size": "768P"
}

{
  "error": {
    "message": "this model takes discrete resolution tiers, not arbitrary sizes: 1280x720 (short side 720). Use a size whose short side is 480 or 768, or pass the tier name directly as size (e.g. \"768P\", \"2K\")",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}

{
  "error": {
    "message": "Model is not available in the model plaza",
    "type": "access_denied",
    "code": "model_not_available"
  }
}

{
  "error": {
    "message": "upstream concurrency full",
    "type": "rate_limit_error",
    "code": "upstream_concurrency_full"
  }
}

• Keep the returned id. If a query hits a network error or times out, keep querying with the same ID rather than resubmitting: resubmitting creates a new task and charges again.
• The concurrency limit behind 429 upstream_concurrency_full is shared per provider account, so switching to another API key does not help; resubmit later.

Retrieve a task

Reads the task's current status; video generation, video upscaling and context enhancement tasks all use this endpoint. The gateway polls the provider for progress in the background, and this endpoint only returns the status the gateway has recorded, so querying more often does not get you the result sooner.

Path parameters

Request examples

curl https://api.lyrouter.com/v1/videos/$TASK_ID \
  -H "Authorization: Bearer $LYROUTER_API_KEY"

import os
import httpx

task_id = "aigwt_minimax_videos_Qm3Tz8VbN1sLk0pYc4dReA"
resp = httpx.get(
    f"https://api.lyrouter.com/v1/videos/{task_id}",
    headers={"Authorization": f"Bearer {os.environ['LYROUTER_API_KEY']}"},
    timeout=60,
)
resp.raise_for_status()
task = resp.json()
print(task["status"], task.get("usage"), task.get("error"))

const taskId = "aigwt_minimax_videos_Qm3Tz8VbN1sLk0pYc4dReA";
const resp = await fetch(`https://api.lyrouter.com/v1/videos/${taskId}`, {
  headers: { Authorization: `Bearer ${process.env.LYROUTER_API_KEY}` },
});
if (!resp.ok) throw new Error(await resp.text());
const task = await resp.json();
console.log(task.status, task.usage, task.error);

Response

When the task exists, the response is always HTTP 200, even if the task itself failed; rely on status for the outcome. A task ID that does not exist, is older than 7 days or belongs to another workspace returns 404.

{
  "id": "aigwt_minimax_videos_Qm3Tz8VbN1sLk0pYc4dReA",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "completed",
  "progress": 100,
  "created_at": 1791950400,
  "completed_at": 1791950507,
  "expires_at": 1792555200,
  "seconds": 5,
  "size": "768P",
  "usage": { "duration_seconds": 5 }
}

{
  "id": "aigwt_minimax_videos-context_Zp8Rk2Vt5Lq9Wx3Ny6Bh1A",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "completed",
  "progress": 100,
  "created_at": 1791950400,
  "completed_at": 1791950421,
  "expires_at": 1792555200,
  "seconds": 5,
  "output_text": "integrated_multimodal_description: [Shot 1] Cinematic, a medium shot featuring a slow push-in on ...",
  "usage": { "completion_tokens": 1820 }
}

{
  "id": "aigwt_minimax_videos_Fj4Ns7Kd2Pw9Lm5Qx8Rt3Y",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "failed",
  "progress": 0,
  "created_at": 1791950400,
  "completed_at": 1791950482,
  "expires_at": 1792555200,
  "seconds": 5,
  "size": "768P",
  "error": {
    "code": "upstream_error",
    "message": "upstream task failed"
  }
}

{
  "error": {
    "message": "video task not found",
    "type": "invalid_request_error",
    "code": "not_found"
  }
}

• For failed tasks, error.code is the provider's error code; when the provider gives no recognizable code, it is upstream_error. error.retryable false means retrying unchanged will not succeed, true means you can retry, and a missing field means the gateway cannot tell. For all values, see Asynchronous tasks.
• Polling interval: start querying about 10 seconds after submitting, then gradually widen to once every 30 seconds.
• Waiting limit: a task still unfinished 24 hours after submission will never produce a result and is not charged, so you can stop polling. At that point the query may still show queued or in_progress; to see the task's actual state, search by task ID on the workspace's Multimedia generation page in the console (State shows Expired).

Download the video

Call it after a video generation or upscaling task becomes completed. It returns 302, and the Location response header is the signed video URL provided by the provider. Let the client follow the redirect to download: add -L in cURL, set follow_redirects=True in Python httpx; Node.js fetch follows redirects by default. A context enhancement task produces text in output_text and has no video to download, so do not call this endpoint for it: currently, calling it on a completed context enhancement task returns HTTP 500 with an HTML page as the body, not a JSON error.

Request examples

# Download to a local file
curl -L https://api.lyrouter.com/v1/videos/$TASK_ID/content \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -o video.mp4

# Get only the video URL without downloading
curl -s -o /dev/null -w '%{redirect_url}\n' \
  https://api.lyrouter.com/v1/videos/$TASK_ID/content \
  -H "Authorization: Bearer $LYROUTER_API_KEY"

import os
import httpx

task_id = "aigwt_minimax_videos_Qm3Tz8VbN1sLk0pYc4dReA"
with httpx.stream(
    "GET",
    f"https://api.lyrouter.com/v1/videos/{task_id}/content",
    headers={"Authorization": f"Bearer {os.environ['LYROUTER_API_KEY']}"},
    follow_redirects=True,
    timeout=600,
) as video:
    video.raise_for_status()
    with open("video.mp4", "wb") as f:
        for chunk in video.iter_bytes():
            f.write(chunk)

import { writeFile } from "node:fs/promises";

const taskId = "aigwt_minimax_videos_Qm3Tz8VbN1sLk0pYc4dReA";
const video = await fetch(`https://api.lyrouter.com/v1/videos/${taskId}/content`, {
  headers: { Authorization: `Bearer ${process.env.LYROUTER_API_KEY}` },
});
if (!video.ok) throw new Error(`download failed: ${video.status}`);
await writeFile("video.mp4", Buffer.from(await video.arrayBuffer()));

Response

Status: 302
Location: <signed video URL provided by the provider>

{
  "error": {
    "message": "video is not ready yet",
    "type": "invalid_request_error",
    "code": "not_ready"
  }
}

{
  "error": {
    "message": "video task not found",
    "type": "invalid_request_error",
    "code": "not_found"
  }
}

• The video URL is fixed when the task completes, and every later call redirects to the same URL. How long the URL stays valid is up to the provider, usually 24 hours; once it expires, it cannot be fetched again through the gateway, so download it or copy it to your own storage as soon as you get it.
• Calling it before the task completes (or after it failed) returns 409. These 4xx responses also count toward the API key's error rate, and frequent calls can trip the circuit breaker, so query until the status is completed before downloading.

Video upscaling

Regenerates a 768P video produced by H3 at 2K; only minimax/minimax-h3 supports it. It works only on H3's own output that meets the 768P spec; it is not a general-purpose upscaler. Submitting returns the same kind of task object: query it with GET /v1/videos/{id} and download it with /content once it completes. Accepts only a JSON request body.

Request body

• Do not send seconds: the duration comes from the source video, and sending it returns 400 seconds is not supported for video regeneration (the source video determines the duration).
• generate_audio, output_format and omni_reference_task_type likewise return 400 <parameter name> is not supported for this model.
• The source video must have an audio track, 24 fps, width and height both divisible by 32, an area between 589,824 and 1,032,192 pixels, and 107–362 frames in total (in steps of 17, roughly 4–15 s).
• The provider requires the prompt and reference materials to match exactly what was used to generate the source video. If they do not match, there is no error; you just do not get the expected result, and the gateway cannot check this for you.

Request examples

curl https://api.lyrouter.com/v1/videos/regenerations \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/minimax-h3",
    "prompt": "The exact final prompt that produced the 768P video",
    "source_video": "https://example.com/h3-768p.mp4",
    "size": "2K"
  }'

import os
import httpx

resp = httpx.post(
    "https://api.lyrouter.com/v1/videos/regenerations",
    headers={"Authorization": f"Bearer {os.environ['LYROUTER_API_KEY']}"},
    json={
        "model": "minimax/minimax-h3",
        "prompt": "The exact final prompt that produced the 768P video",
        "source_video": "https://example.com/h3-768p.mp4",
        "size": "2K",
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["id"])

const resp = await fetch("https://api.lyrouter.com/v1/videos/regenerations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "minimax/minimax-h3",
    prompt: "The exact final prompt that produced the 768P video",
    source_video: "https://example.com/h3-768p.mp4",
    size: "2K",
  }),
});
if (!resp.ok) throw new Error(await resp.text());
console.log((await resp.json()).id);

Response

A successful submission returns HTTP 200 and a task object whose id starts with aigwt_minimax_videos-regenerations_; after completion, usage.duration_seconds is the billed seconds. The 400 below is a request without source_video.

{
  "id": "aigwt_minimax_videos-regenerations_Hk2Lp9WqR4tYv7Xz1Bc3Nd",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0,
  "created_at": 1791950400,
  "expires_at": 1792555200,
  "size": "2K"
}

{
  "error": {
    "message": "source_video is required for video regeneration (the 768P video to upscale)",
    "type": "invalid_request_error",
    "code": "invalid_parameter"
  }
}

Context enhancement

Turns a prompt and its multimodal context into a structured, semantically richer prompt; only minimax/minimax-h3 supports it. This endpoint returns text only; it does not generate a video. It is also an asynchronous task: after submitting, query it with GET /v1/videos/{id}; once it completes, the enhanced prompt is in the task object's output_text, and there is nothing to download from /content. The typical use is two steps: call this endpoint to get output_text, then submit it as the prompt of POST /v1/videos. Accepts only a JSON request body.

This endpoint currently does not reject Seedance models: a Seedance model ID generates a regular video (with no output_text) that is charged as a video. Call this endpoint only with minimax/minimax-h3.

Request body

generate_audio, output_format, omni_reference_task_type and source_video return 400 <parameter name> is not supported for this model.

Request examples

curl https://api.lyrouter.com/v1/videos/context \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/minimax-h3",
    "prompt": "A cat walking down a neon street in the rain",
    "seconds": 5
  }'

import os
import httpx

resp = httpx.post(
    "https://api.lyrouter.com/v1/videos/context",
    headers={"Authorization": f"Bearer {os.environ['LYROUTER_API_KEY']}"},
    json={
        "model": "minimax/minimax-h3",
        "prompt": "A cat walking down a neon street in the rain",
        "seconds": 5,
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["id"])

const resp = await fetch("https://api.lyrouter.com/v1/videos/context", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "minimax/minimax-h3",
    prompt: "A cat walking down a neon street in the rain",
    seconds: 5,
  }),
});
if (!resp.ok) throw new Error(await resp.text());
console.log((await resp.json()).id);

Response

A successful submission returns HTTP 200 and a task object whose id starts with aigwt_minimax_videos-context_. For the completed result, see "200 context enhancement" under "Retrieve a task" above: output_text is the enhanced prompt and usage.completion_tokens is the output token count. The 400 below is the error the provider returns when this endpoint is called with minimax/minimax-h3-max (taken offline); the gateway passes it through as is, without an error.code.

{
  "id": "aigwt_minimax_videos-context_Zp8Rk2Vt5Lq9Wx3Ny6Bh1A",
  "object": "video",
  "model": "MiniMax-H3",
  "status": "queued",
  "progress": 0,
  "created_at": 1791950400,
  "expires_at": 1792555200,
  "seconds": 5
}

{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "invalid params, model MiniMax-H3-Max does not support resolution 2K, supported resolutions: 480P, 768P (2013)",
    "http_code": "400"
  },
  "request_id": "<provider request identifier>"
}

Delete a task

For a finished task (completed or failed), returns HTTP 200 and the task object with "deleted": true; the task record is not deleted, and you can still query and download it until expires_at. Calling it on a task in progress returns 409 cancel_not_supported: the provider offers no cancel endpoint, so wait for the task to end. The official OpenAI SDK's videos.delete() reads this deleted field.

MiniMax-specific parameters and limits

size: the short edge must land exactly on a tier

• 1280x720 has a short edge of 720, which is not a tier, so it is rejected; for 768P write 1366x768 in landscape or 768x1366 in portrait.
• 2K has no fixed short edge; write it only as the tier name "2K".
• With WxH, the aspect ratio must also be one of 21:9, 16:9, 4:3, 1:1, 3:4 or 9:16 (within 2%), otherwise the request returns 400 size implies an aspect ratio this model does not support: <value>.
• The tier sets the resolution tier; the actual pixel size of the output is decided by the provider, so go by the downloaded video. Measured: text to video and omni reference with 480P or 854x480 produce 1038×576 (a short edge of 576, not 480); 768P produces 1344×768; first-and-last-frame image to video with a 1:1 image and 854x480 produces 768×768; upscaling to 2K produces 2560×1440.

Three input scenarios and the aspect ratio

Input material limits

The provider checks the size and aspect ratio of reference materials: when one does not comply, the provider rejects it with error code 2013 and names the offending item (such as content[N].image_url); you are not charged. H3-Max does not support multiple reference images; the provider rejects such requests and suggests using H3 instead (H3-Max has been taken offline by the provider and is currently unavailable).

Billing

• Billed seconds are input plus output, which is usage.duration_seconds on the task object: when you supply a reference video, its seconds count too (for example, a 4-second reference video plus 4 seconds of output gives a duration_seconds of 8). Reference audio is free. Video upscaling does not add them up: duration_seconds counts only the source video's seconds (measured: a 4-second source video is billed as 4).
• Reference images are a separate item (the two models charge different rates for them): for minimax-h3, the first 5 reference images are free, and each one after that is charged. The image count is not in usage; you can see the cost in the logs.
• Context enhancement is billed on input and output tokens separately. The task object's usage lists only completion_tokens (output), but the input tokens are charged as well.
• The price is locked at submission; when the task becomes completed, it is settled on the metering the provider actually returns; failed tasks (including timeouts) are not charged. To see a task's cost in the logs, see Asynchronous tasks.

Complete example

Expands the prompt with context enhancement first, then generates a 768P video with the enhanced prompt, polls until it ends and downloads it. The cURL example requires jq; save it as a script file and run it with bash (it uses exit on errors).

BASE=https://api.lyrouter.com/v1
AUTH="Authorization: Bearer $LYROUTER_API_KEY"

# Submit a task (request body read from stdin) and print the task ID; without a task ID, print the response and fail
submit() {
  local resp id
  resp=$(curl -s "$BASE/$1" -H "$AUTH" -H "Content-Type: application/json" -d @-)
  id=$(echo "$resp" | jq -r '.id // empty')
  if [ -z "$id" ]; then echo "Submission failed: $resp" >&2; return 1; fi
  echo "task: $id" >&2
  echo "$id"
}

# Poll a task until it ends, then print the final task object; fail on a query error or after waiting 2 hours
wait_task() {
  local delay=10 give_up_at=$(( $(date +%s) + 2 * 3600 )) task status
  while [ "$(date +%s)" -le "$give_up_at" ]; do
    sleep $delay
    delay=$(( delay * 3 / 2 > 30 ? 30 : delay * 3 / 2 ))
    task=$(curl -s "$BASE/videos/$1" -H "$AUTH")
    status=$(echo "$task" | jq -r '.status')
    case "$status" in
      completed|failed) echo "$task"; return 0 ;;
      queued|in_progress|"") ;;  # An empty value is usually a network glitch: keep the task ID and query again
      *) echo "Query error: $task" >&2; return 1 ;;
    esac
  done
  echo "$1 is still running; query the same ID again later" >&2; return 1
}

# 1. Context enhancement: get the enhanced prompt; on failure, print the reason and exit
CTX_ID=$(echo '{"model":"minimax/minimax-h3","prompt":"A cat walking down a neon street in the rain","seconds":5}' \
  | submit videos/context) || exit 1
CTX=$(wait_task "$CTX_ID") || exit 1
PROMPT=$(echo "$CTX" | jq -r '.output_text // empty')
if [ -z "$PROMPT" ]; then echo "$CTX" | jq '.error'; exit 1; fi

# 2. Generate the video with the enhanced prompt
VIDEO_ID=$(jq -n --arg p "$PROMPT" \
    '{model:"minimax/minimax-h3",prompt:$p,size:"768P",seconds:5}' \
  | submit videos) || exit 1
TASK=$(wait_task "$VIDEO_ID") || exit 1

# 3. Download on success; print the reason on failure
if [ "$(echo "$TASK" | jq -r '.status')" = "completed" ]; then
  curl -sL "$BASE/videos/$VIDEO_ID/content" -H "$AUTH" -o video.mp4
else
  echo "$TASK" | jq '.error'
fi

import os
import time
import httpx

BASE = "https://api.lyrouter.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['LYROUTER_API_KEY']}"}


def wait_task(client: httpx.Client, task: dict, max_wait: int = 2 * 3600) -> dict:
    """Poll from 10 seconds, widening gradually to 30 seconds, until the task ends."""
    if not task.get("id"):
        raise RuntimeError(f"No task ID returned: {task}")
    print("task:", task["id"])
    delay, give_up_at = 10, time.time() + max_wait
    while task["status"] in ("queued", "in_progress"):
        if time.time() > give_up_at:
            raise TimeoutError(f"{task['id']} is still running; query the same ID again later")
        time.sleep(delay)
        delay = min(delay * 1.5, 30)
        try:
            resp = client.get(f"{BASE}/videos/{task['id']}")
            resp.raise_for_status()
        except httpx.TransportError:
            continue  # Network glitch: keep the task ID and query again; do not resubmit
        task = resp.json()
    if task["status"] == "failed":
        err = task.get("error", {})
        raise RuntimeError(f"{err.get('code')}: {err.get('message')}")
    return task


with httpx.Client(headers=HEADERS, timeout=60) as client:
    # 1. Context enhancement: get the enhanced prompt
    resp = client.post(f"{BASE}/videos/context", json={
        "model": "minimax/minimax-h3",
        "prompt": "A cat walking down a neon street in the rain",
        "seconds": 5,
    })
    resp.raise_for_status()
    prompt = wait_task(client, resp.json())["output_text"]

    # 2. Generate the video with the enhanced prompt
    resp = client.post(f"{BASE}/videos", json={
        "model": "minimax/minimax-h3",
        "prompt": prompt,
        "size": "768P",
        "seconds": 5,
    })
    resp.raise_for_status()
    task = wait_task(client, resp.json())

    # 3. Download: the endpoint returns 302, so follow the redirect
    with client.stream("GET", f"{BASE}/videos/{task['id']}/content",
                       follow_redirects=True, timeout=600) as video:
        video.raise_for_status()
        with open("video.mp4", "wb") as f:
            for chunk in video.iter_bytes():
                f.write(chunk)
    print("Saved video.mp4, usage:", task.get("usage"))

import { writeFile } from "node:fs/promises";

const BASE = "https://api.lyrouter.com/v1";
const headers = { Authorization: `Bearer ${process.env.LYROUTER_API_KEY}` };
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function submit(path, body) {
  const resp = await fetch(`${BASE}${path}`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!resp.ok) throw new Error(await resp.text());
  return resp.json();
}

// Poll from 10 seconds, widening gradually to 30 seconds, until the task ends
async function waitTask(task) {
  if (!task.id) throw new Error(`No task ID returned: ${JSON.stringify(task)}`);
  console.log("task:", task.id);
  let delay = 10_000;
  while (task.status === "queued" || task.status === "in_progress") {
    await sleep(delay);
    delay = Math.min(delay * 1.5, 30_000);
    let resp;
    try {
      resp = await fetch(`${BASE}/videos/${task.id}`, { headers });
    } catch {
      continue; // Network glitch: keep the task ID and query again; do not resubmit
    }
    if (!resp.ok) throw new Error(await resp.text());
    task = await resp.json();
  }
  if (task.status === "failed") {
    throw new Error(`${task.error?.code}: ${task.error?.message}`);
  }
  return task;
}

// 1. Context enhancement: get the enhanced prompt
const ctx = await waitTask(await submit("/videos/context", {
  model: "minimax/minimax-h3",
  prompt: "A cat walking down a neon street in the rain",
  seconds: 5,
}));

// 2. Generate the video with the enhanced prompt
const task = await waitTask(await submit("/videos", {
  model: "minimax/minimax-h3",
  prompt: ctx.output_text,
  size: "768P",
  seconds: 5,
}));

// 3. Download: fetch follows the 302 redirect by default
const video = await fetch(`${BASE}/videos/${task.id}/content`, { headers });
if (!video.ok) throw new Error(`download failed: ${video.status}`);
await writeFile("video.mp4", Buffer.from(await video.arrayBuffer()));
console.log("saved video.mp4", task.usage);

Common errors

Error responses take the form {"error":{"message":"...","type":"...","code":"..."}}.

• Calling video upscaling or context enhancement with another model currently does not always return unsupported_model_operation: Seedance 2.5 on video upscaling returns 400 source_video is not supported for this model (invalid_parameter); a Seedance model on context enhancement is accepted and generates a regular video that is charged as usual; minimax/minimax-h3-max (taken offline) on video upscaling is accepted and a task is created, and on context enhancement gets the provider's 400 passed through (invalid params, model MiniMax-H3-Max does not support resolution 2K, …, without an error.code). Call these two endpoints only with minimax/minimax-h3.
• In a form submission, input_reference accepts only a URL. Currently an uploaded file raises no error: the file is ignored, and the task is generated as if there were no reference video and charged as usual. Only a non-URL text value (such as video.mp4) returns a 400 plain-text error: input_reference must be a URL; uploading a file is not supported by this gateway (pass a publicly reachable https:// URL instead). These plain-text errors from the gateway currently still carry the response header Content-Type: application/json, so check whether the body is JSON before parsing it.
• A duration out of range, mixing image to video with omni reference, non-compliant reference materials and similar problems are rejected by the provider, and the status code and error text are set by the provider; problems found only after submission come back as failed tasks, as described under "Retrieve a task" above. The full list is in Errors and request identifiers.

FAQ

The error says the short edge must be 480 or 768. What should I do?

Answer: MiniMax resolutions are discrete tiers, not arbitrary sizes. Write the tier name directly (such as "768P" or "2K"), or use a size whose short edge is exactly 480 / 768 (such as 1366x768). 2K can only be written as the tier name.

Can H3-Max do video upscaling or context enhancement?

Answer: No. These two endpoints support only minimax/minimax-h3. Currently the gateway does not reject H3-Max outright: video upscaling is accepted and a task is created; context enhancement gets the provider's 400 passed through (invalid params, model MiniMax-H3-Max does not support resolution 2K, …, without an error.code). H3-Max also does not support 2K or a 4-second duration. Moreover, H3-Max has been taken offline by the provider, so even regular video generation is currently unavailable (a call returns HTTP 200, but the task object is empty and has no task ID); use minimax/minimax-h3 instead.

The upscaled video does not look right. What should I do?

Answer: Check three things: the source video is a 768P video produced by H3; prompt is the exact final prompt that was sent to the model when the source video was generated (if context enhancement was used, pass the enhanced prompt); and the reference materials match the ones used then. When these do not match, neither the gateway nor the provider reports an error; you just do not get the expected result.

Context enhancement completed. Why can't I download a video?

Answer: Context enhancement produces only text, found in the task object's output_text; there is no video to download, and calling /content on it currently returns HTTP 500. Submit output_text as the prompt of POST /v1/videos to generate a video.

I sent a reference video. Why are the billed seconds longer than the video?

Answer: MiniMax bills input plus output seconds: the seconds of the reference video also count toward usage.duration_seconds. Reference audio is free, and the first 5 reference images are free, with each one after that charged.

I sent a reference video and the task failed with aspect ratio "adaptive" is not supported. What should I do?

Answer: The full error is h3submit: aspect ratio "adaptive" is not supported for task ref2va. With a reference video (input_reference), MiniMax requires an explicit aspect ratio, but when size is a tier name (such as 480P) the gateway sends an adaptive ratio. Change size to WxH with a short side of 480 or 768, such as 854x480 or 1366x768, and submit again. Failed tasks like this are not charged.

The video URL has expired. Can I download it again?

Answer: No. The video URL is fixed when the task completes, and calling /content again returns the same URL, so after it expires you need to submit a new task. Download the video or copy it to your own storage right after the task completes.

The query keeps returning in_progress. What should I do?

Answer: Video generation usually takes several minutes. A task still unfinished 24 hours after submission will never produce a result and is not charged, so you can stop polling and check the task's state by task ID on the Multimedia generation page in the console. Do not resubmit the same request while you wait: each submission creates a new task that is charged separately.