# MiniMax H3

Create a video task with this model, then query its result using the returned task ID.

Model ID `minimax-h3`

## Quickstart

Create an [API key](/me?section=api-keys) and set `I2V_API_KEY`. Set `IDEMPOTENCY_KEY` once for each new task. Reuse the key and identical payload when retrying that submission.

### Submit a task

`POST https://api.i2v.ai/api/v1/jobs/createTask`

```bash
curl "https://api.i2v.ai/api/v1/jobs/createTask" \
  -H "Authorization: Bearer $I2V_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
  "model": "minimax-h3",
  "inputs": {
    "prompt": "A calm lake at sunrise",
    "duration": 5
  }
}'
```

HTTP 200 means the task was accepted. Save the returned `taskId`.

```json
{"taskId":"YOUR_TASK_ID"}
```

### Query the result

```bash
curl "https://api.i2v.ai/api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID" \
  -H "Authorization: Bearer $I2V_API_KEY"
```

Replace `YOUR_TASK_ID` with the returned ID. Poll with backoff while the status is `waiting` or `generating`. Read `output[].url` on `success`, or inspect `error` on `fail`.

## Parameters

Send model inputs inside `inputs`. Media URLs must be publicly accessible. Required media and supported combinations depend on the selected generation mode.

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `inputs.prompt` | string | No | — | Text describing the result or requested edit. Maximum 7000 characters. |
| `inputs.resolution` | string | No | — | Output resolution. Allowed `768p`, `2k`. |
| `inputs.aspectRatio` | string | No | — | Output aspect ratio. Allowed `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`. |
| `inputs.duration` | number | No | 5 | Video duration in seconds. Allowed `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`. |
| `inputs.urls` | string[] | No | — | Keyframe image URLs. The first two entries are the first and last frames. Maximum 2 URLs. |
| `inputs.referenceImageUrls` | string[] | No | — | Reference image URLs. Maximum 9 URLs. |
| `inputs.referenceVideoUrls` | string[] | No | — | Reference video URLs. Maximum 3 URLs. |
| `inputs.referenceAudioUrls` | string[] | No | — | Reference audio URLs. Maximum 3 URLs. |
| `inputs.videoUrl` | string | No | — | Source video URL for video-to-video generation. |

### Top-level request fields

| Field | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `model` | string | Yes | `minimax-h3` | Public model ID. Use the exact value shown above. |
| `maxCostUsd` | string | No | — | Optional USD ceiling as a decimal string with up to eight fractional digits. A higher quote returns HTTP 409 before generation. |
| `callBackUrl` | string | No | — | Optional public HTTPS callback URL. Configure signing in [Webhooks](/docs/webhooks). |
| `expectedRevision` | number | No | — | Optional published model revision for optimistic concurrency checks. |

## Response

Illustrative successful response. Output URLs are placeholders. Actual USD charges depend on the submitted inputs. Pending tasks may contain null values.

```json
{
  "taskId": "YOUR_TASK_ID",
  "model": "minimax-h3",
  "status": "success",
  "billing": null,
  "output": [
    {
      "url": "https://example.com/result.mp4"
    }
  ],
  "error": null,
  "createTime": 1760000000000,
  "completeTime": 1760000060000
}
```

| Status | Meaning |
| --- | --- |
| `waiting` | Queued |
| `generating` | Generating |
| `success` | Completed. Read output[].url. |
| `fail` | Failed. Inspect error.code and error.message. |

## Code examples

### Node.js

```javascript
const baseUrl = "https://api.i2v.ai";
if (!process.env.I2V_API_KEY || !process.env.IDEMPOTENCY_KEY) {
  throw new Error('Set I2V_API_KEY and a stable IDEMPOTENCY_KEY before submitting.');
}
const headers = {
  Authorization: `Bearer ${process.env.I2V_API_KEY}`,
  'Content-Type': 'application/json',
  'Idempotency-Key': process.env.IDEMPOTENCY_KEY,
};
const response = await fetch(baseUrl + '/api/v1/jobs/createTask', {
  method: 'POST', headers,
  body: JSON.stringify({
  "model": "minimax-h3",
  "inputs": {
    "prompt": "A calm lake at sunrise",
    "duration": 5
  }
}),
});
const created = await response.json();
if (!response.ok) throw new Error(JSON.stringify(created));

const deadline = Date.now() + 30 * 60_000;
let delayMs = 2_000;
let output;
while (Date.now() < deadline) {
  const result = await fetch(baseUrl + '/api/v1/jobs/recordInfo?taskId=' + encodeURIComponent(created.taskId), { headers });
  const task = await result.json();
  if (!result.ok || task.status === 'fail') throw new Error(JSON.stringify(task));
  if (task.status === 'success') {
    output = task.output;
    break;
  }
  await new Promise(resolve => setTimeout(resolve, delayMs));
  delayMs = Math.min(delayMs * 1.5, 30_000);
}
if (!output) throw new Error('Polling timed out. Resume with taskId ' + created.taskId);
console.log(output.map(item => item.url));
```

### Python

```python
import json
import os
import time
import urllib.parse
import urllib.request

base_url = "https://api.i2v.ai"
headers = {
    'Authorization': 'Bearer ' + os.environ['I2V_API_KEY'],
    'Content-Type': 'application/json',
    'Idempotency-Key': os.environ['IDEMPOTENCY_KEY'],
}
payload = json.loads("{\"model\":\"minimax-h3\",\"inputs\":{\"prompt\":\"A calm lake at sunrise\",\"duration\":5}}")
request = urllib.request.Request(
    base_url + '/api/v1/jobs/createTask',
    data=json.dumps(payload).encode(), headers=headers, method='POST',
)
with urllib.request.urlopen(request, timeout=60) as response:
    created = json.load(response)

deadline = time.monotonic() + 30 * 60
delay = 2
while time.monotonic() < deadline:
    query = urllib.parse.urlencode({'taskId': created['taskId']})
    request = urllib.request.Request(base_url + '/api/v1/jobs/recordInfo?' + query, headers=headers)
    with urllib.request.urlopen(request, timeout=60) as response:
        task = json.load(response)
    if task['status'] == 'fail':
        raise RuntimeError(task['error'])
    if task['status'] == 'success':
        print([item['url'] for item in task['output']])
        break
    time.sleep(delay)
    delay = min(delay * 1.5, 30)
else:
    raise TimeoutError('Polling timed out. Resume with taskId ' + created['taskId'])
```

## Pricing

Published USD prices for each configuration and billing unit.

| Mode | Resolution | Duration | USD | Unit |
| --- | --- | --- | --- | --- |
| standard | 768p | — | 0.05128205 USD | second |
| standard | 2k | — | 0.08058608 USD | second |

## Errors and retries

Common submission errors include `400 invalid_params`, `401 unauthorized`, `402 insufficient_balance`, `409 conflict`, and `429 concurrency_limit` / `rate_limit`. See [errors and retries](/docs/errors) for recovery and [Webhooks](/docs/webhooks) for signed completion events.