minimax-video · diff
v1.0 to v1.0
67 added, 40 removed. Audit A to A.
---
name: minimax-video
- description: Generate MiniMax H3 videos from text, up to nine reference images, or up to three audio references through AceDataCloud. Use for text-to-video, multi-image video, audio-guided video, and MiniMax H3 task polling.
+ 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).
---
# MiniMax H3 Video Generation
- Generate 4–15 second videos through `POST https://api.acedata.cloud/minimax/videos`.
+ 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). For long jobs, use [async task polling](../_shared/async-tasks.md) with `POST /minimax/tasks`.
## Contract
| Parameter | Values | Default |
| --- | --- | --- |
- | `model` | `minimax-h3` | `minimax-h3` |
- | `prompt` | non-empty string, max 7000 chars | required |
- | `image_urls` | 1–9 public HTTP(S) URLs | omitted |
- | `audio_urls` | 1–3 public HTTP(S) URLs | omitted |
- | `resolution` | `768P`, `2K` | `2K` |
- | `ratio` | `16:9`, `9:16` | `16:9` |
- | `duration` | integer 4–15 | 4 |
- | `async` | boolean | false |
+ | `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 |
| `callback_url` | public HTTP(S) webhook | omitted |
- `prompt` is required in every mode. Audio also requires at least one image. Mode inference is deterministic:
+ 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`:
- 1. `audio_urls` present → audio-guided video
- 2. otherwise `image_urls` present → image-to-video
- 3. otherwise → text-to-video
+ | Role | Use |
+ | --- | --- |
+ | `first_frame` | Starting image |
+ | `last_frame` | Ending image |
+ | `reference_image` | Reference image |
+ | `reference_video` | Reference video |
+ | `reference_audio` | Reference audio |
- Public pricing is **$0.057143/s for 768P** and **$0.091429/s for 2K** on the largest package. Failed tasks are not charged.
+ 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 "Authorization: ******" \
-H "Content-Type: application/json" \
-d '{
- "model": "minimax-h3",
- "prompt": "A red fox running through a snowy forest at dawn, low tracking shot",
+ "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
+ "duration": 4
}'
```
- ## Multi-image video
+ ## First and last frame video
```json
{
- "model": "minimax-h3",
- "prompt": "Preserve the character and clothing while the camera slowly pushes in",
- "image_urls": [
- "https://cdn.acedata.cloud/b1c82e4937.png",
- "https://cdn.acedata.cloud/eb75d88a3f.png"
+ "model": "MiniMax-H3",
+ "content": [
+ {
+ "type": "text",
+ "text": "A camera slowly pushes in as the character walks into the sunrise."
+ },
+ {
+ "type": "image_url",
+ "image_url": "https://cdn.acedata.cloud/first-frame.png",
+ "role": "first_frame"
+ },
+ {
+ "type": "image_url",
+ "image_url": "https://cdn.acedata.cloud/last-frame.png",
+ "role": "last_frame"
+ }
],
"resolution": "768P",
"ratio": "9:16",
- "duration": 8,
- "async": true
+ "duration": 8
}
```
- ## Audio-guided video
+ ## Reference-guided video
```json
{
- "model": "minimax-h3",
- "prompt": "A dancer moves naturally to the rhythm",
- "image_urls": ["https://cdn.acedata.cloud/b1c82e4937.png"],
- "audio_urls": ["https://cdn.acedata.cloud/6f7d62b18b.wav"],
+ "model": "MiniMax-H3",
+ "content": [
+ {
+ "type": "text",
+ "text": "A dancer moves naturally to the rhythm."
+ },
+ {
+ "type": "image_url",
+ "image_url": "https://cdn.acedata.cloud/reference.png",
+ "role": "reference_image"
+ },
+ {
+ "type": "audio_url",
+ "audio_url": "https://cdn.acedata.cloud/reference.wav",
+ "role": "reference_audio"
+ }
+ ],
"resolution": "768P",
"ratio": "9:16",
- "duration": 8,
- "async": true
+ "duration": 8
}
```
## Poll a task
```bash
curl -X POST https://api.acedata.cloud/minimax/tasks \
- -H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
+ -H "Authorization: ******" \
-H "Content-Type: application/json" \
-d '{"action":"retrieve","id":"TASK_ID"}'
```
- Continue polling about every five seconds until `response.success` is true or an error appears. Use `retrieve_batch` with `ids` to check several tasks in one request.
+ Continue polling about every five seconds until the task reaches a terminal state. Use `retrieve_batch` with `ids` to check several tasks, or `delete` with `id` to remove a task. Batch listing also accepts `limit`, `offset`, `created_at_min`, and `created_at_max`.
## Gotchas
- Do not send `action` to `/minimax/videos`; the API infers the mode from media inputs.
- `duration` must be an integer, not a decimal.
- - Audio mode requires both `prompt` and at least one `image_urls` entry.
- - Single-image mode uses the image as the first frame; multiple images are references.
- - Use public URLs that the generation service can download.
+ - 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.