Minimax Video

---
name: minimax-video
description: Generate MiniMax H3 videos from text and optional image, video, or audio references through AceDataCloud. Use for text-to-video, first/last-frame video, multimodal reference video, and MiniMax H3 task polling.
license: Apache-2.0
metadata:
  author: acedatacloud
  version: "1.0"
compatibility: Requires ACEDATACLOUD_API_TOKEN in .env (see _shared/authentication.md). Optionally pair with mcp-minimax for tool-use.
---

# MiniMax H3 Video Generation

Generate 4–15 second videos through `POST https://api.acedata.cloud/minimax/videos`. Use the V2 multimodal `content` array to supply the prompt and optional reference media.

> **Setup:** See [authentication](../_shared/authentication.md). The HTTP API waits for the final result by default. Agents and MCP clients should send `"async": true`, save the returned `task_id`, then use [async task polling](../_shared/async-tasks.md) with `POST /minimax/tasks`. MiniMax MCP generation tools expose `async` and default it to `true`.

## Contract

| Parameter | Values | Default |
| --- | --- | --- |
| `model` | `MiniMax-H3` | required |
| `content` | array of prompt and optional media items | required |
| `resolution` | `768P`, `2K` | required |
| `duration` | integer 4–15 | required |
| `ratio` | `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` | omitted |
| `async` | `true`, `false` | `false` at the HTTP API; `true` in MiniMax MCP tools |
| `callback_url` | public HTTP(S) webhook; also enables async mode | omitted |

Each `content` item has a `type` of `text`, `image_url`, `video_url`, or `audio_url`; set the matching field to the text or public URL. Media items use a `role`:

| Role | Use |
| --- | --- |
| `first_frame` | Starting image |
| `last_frame` | Ending image |
| `reference_image` | Reference image |
| `reference_video` | Reference video |
| `reference_audio` | Reference audio |

Include a `text` item with the generation prompt in every request.

## Text to video

```bash
curl -X POST https://api.acedata.cloud/minimax/videos \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "A red fox running through a snowy forest at dawn, low tracking shot"
      }
    ],
    "resolution": "768P",
    "ratio": "16:9",
    "duration": 4,
    "async": true
  }'
```

## First and last frame video

```json
{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "A camera slowly pushes in as the character walks into the sunrise."
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://cdn.acedata.cloud/first-frame.png"},
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://cdn.acedata.cloud/last-frame.png"},
      "role": "last_frame"
    }
  ],
  "resolution": "768P",
  "ratio": "9:16",
  "duration": 8,
  "async": true
}
```

## Reference-guided video

```json
{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "A dancer moves naturally to the rhythm."
    },
    {
      "type": "image_url",
      "image_url": {"url": "https://cdn.acedata.cloud/reference.png"},
      "role": "reference_image"
    },
    {
      "type": "audio_url",
      "audio_url": {"url": "https://cdn.acedata.cloud/reference.wav"},
      "role": "reference_audio"
    }
  ],
  "resolution": "768P",
  "ratio": "9:16",
  "duration": 8,
  "async": true
}
```

## Poll a task

```bash
curl -X POST https://api.acedata.cloud/minimax/tasks \
  -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"retrieve","id":"TASK_ID"}'
```

Continue polling about every five seconds while `task.status` is `queued` or `running`. Only `task.status="succeeded"` is success; then read the final video URL from `task.content.url`. If the task is `failed` or `cancelled`, stop polling and report `task.error.code` / `task.error.message` when present. A returned `task_id` or HTTP 200 means acceptance, not a finished video; never report a URL as final before success.

Use `retrieve_batch` with `ids` to check several tasks; inspect each item in `items` independently. Use `delete` with `id` to remove a task record, not to cancel generation. Batch listing also accepts `limit`, `offset`, `created_at_min`, and `created_at_max`.

> **MCP:** `pip install mcp-minimax` | Hosted: `https://minimax.mcp.acedata.cloud/mcp` | See [MCP setup](../_shared/mcp-servers.md). Current generation supports `MiniMax-H3` with `768P` or `2K`; keep querying the returned task ID until terminal success or failure.

## Gotchas

- Do not send `action` to `/minimax/videos`; the API infers the mode from media inputs.
- `duration` must be an integer, not a decimal.
- Put the prompt in a `content` item with `type: "text"`; do not send a top-level `prompt`.
- Use `first_frame`, `last_frame`, and reference roles explicitly; do not rely on item order to determine an image's role.
- Use public URLs that the generation service can download for every media item.
- Returned videos are served from AceDataCloud CDN.