# MiniMax-H3

Canonical page: https://agentsky.dev/models/minimax/MiniMax-H3
JSON record: https://gateway.agentsky.dev/v1/endpoints/minimax/MiniMax-H3

MiniMax-H3 is a video model from MiniMax, callable through the AgentSky API as minimax/MiniMax-H3 and billed per second (480p: $0.056 · 768p (default): $0.056 · 1080p: $0.056 · 2K: $0.091 · 4K: $0.14).

Generate video using the supplier configured for your account plan. The pricing table lists each resolution once with your price per second; unsupported resolutions are unavailable. Send provider minimax and endpoint MiniMax-H3. The quality parameter does not override your configured supplier. Supported durations and reference options depend on the configured supplier. Accepted tasks are checkpointed. If a run is RUNNING, poll GET /v1/runs/{runId}; after a network timeout, repeat the identical request with the same Idempotency-Key to recover it.

After COMPLETED, read run.output.video_url, run.output.duration and run.output.resolution. Duration reporting and whole-second billing follow your configured supplier. Download the temporary video URL promptly.

## Facts

- **Id:** `minimax/MiniMax-H3`
- **Provider:** MiniMax
- **Kind:** video model
- **Billed per:** second
- **Timeout:** 14 min
- **Max request:** 1 MB

## Call it

`POST https://gateway.agentsky.dev/v1/run` with `{"provider": "minimax", "endpoint": "MiniMax-H3", "input": {…}}` and `Authorization: Bearer $AGENTSKY_API_KEY`.

### Input fields

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | yes | Describe the scene and movement. The maximum prompt length depends on the supplier configured for your account plan. |
| `duration_s` | number | no | Requested duration. Supported values and whole-second billing behavior follow your configured supplier. Default: 4. Min: 3. Max: 15. |
| `resolution` | string | no | Output resolution. Availability follows your configured supplier; resolution spelling is case-insensitive. Allowed: 480p, 768p, 768P, 1080p, 2K, 4K. |
| `quality` | string | no | Optional quality setting when supported by your configured supplier. This does not select a different supplier. Allowed: low, high. |
| `aspect_ratio` | string | no | Output aspect ratio. Adaptive frame sizing is available when supported by your configured supplier. Allowed: 16:9, 9:16, 1:1, 4:3, 3:4, 21:9, adaptive. Default: "1:1". |
| `first_frame_image_url` | string | no | HTTPS first frame image; cannot combine with reference images. |
| `last_frame_image_url` | string | no | HTTPS last frame image; cannot combine with reference images and may require a first frame. |
| `reference_image_url` | array | no | HTTPS reference images; the configured supplier determines the maximum count. Cannot combine with frame images. |

## Example

### curl

```bash
# Set once per job; reuse this key and the identical body after a timeout.
: "${AGENTSKY_IDEMPOTENCY_KEY:?Set a unique, saved key for this job}"
curl --fail-with-body https://gateway.agentsky.dev/v1/run \
  -H "authorization: Bearer $AGENTSKY_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $AGENTSKY_IDEMPOTENCY_KEY" \
  -d '{"provider":"minimax","endpoint":"MiniMax-H3","input":{"prompt":"A small blue sphere slowly rotates on a white background.","duration_s":4,"resolution":"768p"}}'
# If status is READY/RUNNING, poll GET /v1/runs/{runId} with the same API key.
```

### JavaScript

```js
// Node.js 20+. Save one unique key per job; reuse it with the identical body.
const key = process.env.AGENTSKY_IDEMPOTENCY_KEY;
if (!key || !process.env.AGENTSKY_API_KEY) {
  throw new Error("Set AGENTSKY_API_KEY and a saved AGENTSKY_IDEMPOTENCY_KEY first");
}
const base = "https://gateway.agentsky.dev";
const headers = {
  authorization: `Bearer ${process.env.AGENTSKY_API_KEY}`,
  "content-type": "application/json",
  "Idempotency-Key": key,
};
const body = JSON.stringify({
  "provider": "minimax",
  "endpoint": "MiniMax-H3",
  "input": {
    "prompt": "A small blue sphere slowly rotates on a white background.",
    "duration_s": 4,
    "resolution": "768p"
  }
});
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function request(path, options = {}) {
  for (let attempt = 0; attempt < 3; attempt++) {
    let response;
    let data;
    try {
      response = await fetch(base + path, {
        ...options, headers, signal: AbortSignal.timeout(180_000),
      });
      const text = await response.text();
      try { data = JSON.parse(text); } catch { /* Proxy timeouts may return HTML. */ }
    } catch (error) {
      if (attempt === 2) throw error; // Resume with the same key and body.
      await sleep(2000);
      continue;
    }
    // Failed runs can have non-2xx HTTP status. Never regenerate them automatically.
    if (data?.runId && data?.status) return data;
    if (response.ok && data) throw new Error("Unexpected response: missing runId/status");
    if (attempt < 2 && (response.status >= 500 || response.status === 408 || response.status === 429)) {
      await sleep(2000);
      continue; // POST retries keep the original key and body.
    }
    throw new Error(`HTTP ${response.status}: ${JSON.stringify(data ?? "Non-JSON response; retry with the same key and body")}`);
  }
}

let run = await request("/v1/run", { method: "POST", body });
console.log("Save runId:", run.runId);
const deadline = Date.now() + 30 * 60_000;
while (["READY", "RUNNING"].includes(run.status)) {
  if (Date.now() >= deadline) {
    throw new Error(`Still pending: poll /v1/runs/${run.runId} later; do not create a new job`);
  }
  await sleep(5000);
  run = await request(`/v1/runs/${encodeURIComponent(run.runId)}`);
}
console.log("Status:", run.status, "Charge:", run.price?.amount);
if (run.status !== "COMPLETED") {
  throw new Error(`Run ${run.runId}: ${JSON.stringify(run.error ?? run.status)}`);
}
console.log(run.output); // Output shape depends on the endpoint.
// READY/RUNNING price is provisional. Use the terminal receipt for reconciliation.
```

## Pricing

| Input conditions | Availability | USD per second |
|---|---|---|
| 480p | Available | $0.056 |
| 768p (default) | Available | $0.056 |
| 1080p | Available | $0.056 |
| 2K | Available | $0.091 |
| 4K | Available | $0.14 |

Read the final customer charge from price.amount.value after the run finishes. A RUNNING response is not the final bill.

## Questions

### What does MiniMax-H3 do?

Generate video using the supplier configured for your account plan. The pricing table lists each resolution once with your price per second; unsupported resolutions are unavailable. Send provider minimax and endpoint MiniMax-H3. The quality parameter does not override your configured supplier. Supported durations and reference options depend on the configured supplier. Accepted tasks are checkpointed. If a run is RUNNING, poll GET /v1/runs/{runId}; after a network timeout, repeat the identical request with the same Idempotency-Key to recover it.

### How much does MiniMax-H3 cost?

480p: Reference $0.08; plan price $0.056 · 768p (default): Reference $0.08; plan price $0.056 · 1080p: Reference $0.08; plan price $0.056 · 2K: Reference $0.13; plan price $0.091 · 4K: Reference $0.20; plan price $0.14 per second, using your plan when signed in. The customer charge is returned as price.amount.value with its currency; READY/RUNNING values are provisional.

### What does MiniMax-H3 take?

prompt is required; the rest of the fields are optional. Send them in the input object of a POST to /v1/run.

### What are the limits on MiniMax-H3?

The catalog lists an execution timeout of 14 min. A request can return READY or RUNNING before completion; poll GET /v1/runs/{runId} with the same API key until it reaches a terminal status. An HTTP timeout does not prove the generation stopped.

### How do I retry safely and check the final charge?

Save a unique Idempotency-Key for each job. After a network error or HTML timeout, resend the identical POST body with the same key and API key to recover the existing run, then poll its runId. A new key can start another billable generation. An HTTP error or timeout does not establish the run outcome or final charge. Pending runs can still settle; check the terminal price.amount and billing state, and retain the runId for reconciliation. Do not automatically create a new job after a terminal failure.
