# wavespeed-ai/minimax-h3/reference-to-video

> MiniMax H3 Open Weights Reference to Video generates coherent 480P / 540P / 768P videos from prompts and multimodal references, guided by up to 9 reference images, 3 reference videos, and 3 reference audios, with native stereo audio and flexible reference-based video generation on WaveSpeedAI infrastructure. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

## Overview

- **Endpoint**: `https://api.wavespeed.ai/api/v3/wavespeed-ai/minimax-h3/reference-to-video`
- **Polling/result URL**: `https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result`
- **Model ID**: `wavespeed-ai/minimax-h3/reference-to-video`
- **Category**: reference-to-video

## Pricing

Output video is billed per generated second (up to 15 seconds), and the rate depends on the resolution. Each reference video is also billed per second at the same resolution rate, rounded up to whole seconds and counted up to 15 seconds in total. Each reference image and each reference audio adds a flat charge.

**Output video, no references** (price of a request with only `resolution` and `duration` set):

| Resolution | 3 s | 5 s | 10 s | 15 s | Per second (`duration`) |
|-----------|----:|----:|-----:|-----:|-----:|
| 480p | ~~$0.15~~ $0.075 | ~~$0.25~~ $0.125 | ~~$0.50~~ $0.25 | ~~$0.75~~ $0.375 | ~~$0.05~~ $0.025 |
| 540p | ~~$0.225~~ $0.1125 | ~~$0.375~~ $0.1875 | ~~$0.75~~ $0.375 | ~~$1.125~~ $0.5625 | ~~$0.075~~ $0.0375 |
| 768p | ~~$0.30~~ $0.15 | ~~$0.50~~ $0.25 | ~~$1.00~~ $0.50 | ~~$1.50~~ $0.75 | ~~$0.10~~ $0.05 |
| 1080p | ~~$0.60~~ $0.30 | ~~$1.00~~ $0.50 | ~~$2.00~~ $1.00 | ~~$3.00~~ $1.50 | ~~$0.20~~ $0.10 |

Default settings (768p, 5 s) cost ~~$0.50~~ $0.25 per run.

**Reference video** - added per second of reference video, at the resolution of the output:

| Resolution | 1 s of reference video (`reference_videos.seconds=1`) | 2 s of reference video (`reference_videos.seconds=2`) minus 1 s |
|-----------|-----:|-----:|
| 480p | ~~$0.05~~ $0.025 | ~~$0.05~~ $0.025 |
| 540p | ~~$0.075~~ $0.0375 | ~~$0.075~~ $0.0375 |
| 768p | ~~$0.10~~ $0.05 | ~~$0.10~~ $0.05 |
| 1080p | ~~$0.20~~ $0.10 | ~~$0.20~~ $0.10 |

**Reference images and audios** - flat charge, independent of resolution and duration:

| Item | Price |
|------|------:|
| Each additional reference image (`reference_images.count=2` minus `reference_images.count=1`) | ~~$0.02~~ $0.01 |
| Each additional reference audio (`reference_audios.count=2` minus `reference_audios.count=1`) | ~~$0.02~~ $0.01 |

*Example: a 10 s 480p video (`duration=10`, `resolution=480p`) with 2 reference images and a 5 s reference video costs ~~$0.79~~ $0.395.*

---

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
The API is asynchronous: submit a prediction, then poll its result URL until it completes.

### Input Schema

The API accepts the following input parameters:

- **`prompt`** (`string`, _required_):
  Text description of the desired video. Refer to reference inputs as <Picture 1>..<Picture 9>, <Video 1>..<Video 3>, and <Audio 1>..<Audio 3>. Audio is generated natively together with the video.

- **`reference_images`** (`array of string`, _optional_):
  Reference image URLs (up to 9). At least one reference input is required.

- **`reference_videos`** (`array of string`, _optional_):
  Reference video URLs (up to 3, usable at any output resolution). Their soundtracks are used automatically. Total reference video duration is budgeted to 15 seconds; longer inputs are truncated fairly.

- **`reference_audios`** (`array of string`, _optional_):
  Standalone reference audio URLs (up to 3, trimmed to 15 seconds each).

- **`aspect_ratio`** (`string`, _optional_):
  Output aspect ratio.
  - Default: `"16:9"`
  - Options: "16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "9:21"

- **`resolution`** (`string`, _optional_):
  Output video resolution. 768p is the model's native canvas; 480p is a faster, lower-cost tier; 540p is a mid tier at 1.5x the 480p price. 1080p is the highest-quality full-HD tier at 2x the 768p price (generation takes longer).
  - Default: `"768p"`
  - Options: "480p", "540p", "768p", "1080p"

- **`duration`** (`integer`, _optional_):
  Output video duration in seconds.
  - Default: `5`
  - Options: 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15

- **`enable_prompt_expansion`** (`boolean`, _optional_):
  Expand the prompt into a detailed description before generation when that helps. Turn off to use the prompt exactly as written.
  - Default: `true`

- **`seed`** (`integer`, _optional_):
  The random seed to use for the generation. -1 means a random seed will be used.



**Required Parameters Example**:

```json
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed"
}
```

**Full Example**:

```json
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "reference_images": [],
  "reference_videos": [],
  "reference_audios": [],
  "aspect_ratio": "16:9",
  "resolution": "768p",
  "duration": 5,
  "enable_prompt_expansion": true,
  "seed": 0
}
```

### Result Data Schema

The `data` object returned by the API has the following fields:

- **`created_at`** (`string (date-time)`, _optional_):
  ISO timestamp of when the request was created (e.g., "2023-04-01T12:34:56.789Z").

- **`id`** (`string`, _optional_):
  Unique identifier for the prediction, the ID of the prediction to get.

- **`model`** (`string`, _optional_):
  Model ID used for the prediction.

- **`outputs`** (`array of string | object`, _optional_):
  Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model.

- **`status`** (`string`, _optional_):
  Status of the task: created, processing, completed, or failed.

- **`urls`** (`object`, _optional_):
  Object containing related API endpoints.



**Example `data` Object**:

```json
{
  "created_at": "example",
  "id": "example",
  "model": "example",
  "outputs": [],
  "status": "example",
  "urls": {}
}
```

## Usage Examples

The examples use `jq` to read JSON. Set your API key first:

```bash
set -euo pipefail
export WAVESPEED_API_KEY="your-api-key"
```

### 1. Submit a prediction

```bash
REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed"
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url https://api.wavespeed.ai/api/v3/wavespeed-ai/minimax-h3/reference-to-video \
  --header "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "${REQUEST_BODY}")

printf '%s\n' "${SUBMIT_RESPONSE}" | jq .
```

The response contains the prediction ID in `data.id`.

### 2. Poll until complete and read `outputs`

```bash
PREDICTION_ID=$(printf '%s' "${SUBMIT_RESPONSE}" | jq -r '.data.id')
if [ -z "${PREDICTION_ID}" ] || [ "${PREDICTION_ID}" = "null" ]; then
  printf 'Submission response did not contain data.id\n' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    --request GET \
    --url "${RESULT_URL}" \
    --header "Authorization: Bearer ${WAVESPEED_API_KEY}")

  RESULT=$(printf '%s' "${RESPONSE}" | jq -e '.data')
  STATUS=$(printf '%s' "${RESULT}" | jq -er '.status')
  case "${STATUS}" in
    completed)
      # Generated files are returned in the outputs array.
      printf '%s\n' "${RESULT}" | jq '.outputs'
      break
      ;;
    failed|cancelled|timeout|deleted)
      printf '%s\n' "${RESULT}" | jq '{status, error, code}'
      exit 1
      ;;
    *)
      sleep 2
      ;;
  esac
done
```

## Additional Resources

### Documentation

- [Model Playground](https://wavespeed.ai/models/wavespeed-ai/minimax-h3/reference-to-video)
- [API Documentation](https://wavespeed.ai/docs/docs-api/wavespeed-ai/minimax-h3-reference-to-video)
