# minimax/h3-max/reference-to-video

> H3 Max generates a video from a text prompt and reference images, videos, or audio. Reference assets can be combined to preserve subject, motion, style, or audio characteristics.

## Overview

- **Endpoint**: `https://api.shortapi.ai/api/v1/job/create`
- **Model ID**: `minimax/h3-max/reference-to-video`
- **Category**: reference-to-video
- **Kind**: inference

## Pricing

480P: $0.05 per output second. 768P: $0.08 per output second. 1080P: $0.16 per output second.

For more details, please check our pricing page.

## API Information

This model can be used via our HTTP API or more conveniently via our client libraries.
See the input and output schema below, as well as the usage examples.

### Input Schema

The API accepts the following input parameters:

- **`prompt`** (`string`, _required_):
  Text prompt describing the expected generated video. Refer to assets as Image 1, Video 1, or Audio 1. Maximum 50,000 characters.
  - Examples: "An action shot of a black lab swimming..."

- **`reference_image_urls`** (`list<string>`, _optional_):
  Optional reference image URLs or Base64 images. Up to 9 images; all reference assets combined must not exceed 12 files.

- **`reference_video_urls`** (`list<string>`, _optional_):
  Optional reference video URLs. Up to 3 videos; each must be 2 to 15 seconds. Video and audio durations combined must not exceed 15 seconds.

- **`reference_audio_urls`** (`list<string>`, _optional_):
  Optional reference audio URLs. Up to 3 clips; each must be 2 to 15 seconds. Video and audio durations combined must not exceed 15 seconds.

- **`duration`** (`int`, _optional_):
  Output video duration in seconds. Supported range: 5 to 15 seconds.
  - Default: `5`
  - Range: `5` to `15`

- **`resolution`** (`string`, _optional_):
  Output video resolution.
  - Default: `768P`
  - Options: "480P", "768P", "1080P"

- **`prompt_expansion_mode`** (`string`, _optional_):
  Controls prompt rewriting quality and latency.
  - Default: `balanced`
  - Options: "disabled", "balanced", "quality"

- **`aspect_ratio`** (`string`, _optional_):
  Output video aspect ratio. Use adaptive to follow the reference material when appropriate.
  - Default: `adaptive`
  - Options: "adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16"

### Output Schema

The API returns a JSON response with a `job_id` for tracking the request status.

**Create Job Response:**
```json
{
  "code": 0,
  "data": {
    "amount": "0.02",
    "job_id": "<JOB_ID>"
  }
}
```

**Query Job Result (when status is 2, meaning succeeded):**
```json
{
  "code": 0,
  "data": {
    "status": 2,
    "result": {
      "videos": [{ "url": "https://..." }]
    }
  }
}
```

## Use Example

To use this model, make an HTTP POST request to the API endpoint, then poll for results using the returned `job_id`.

### Bash (cURL)
```bash
# Step 1: Create a job
response=$(curl --request POST \
  --url https://api.shortapi.ai/api/v1/job/create \
  --header "Authorization: Bearer $SHORTAPI_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "minimax/h3-max/reference-to-video",
  "args": {
    "prompt": "Figure 2 serves as a reference for fixed characters, maintaining consistent elements such as black half-up long hair, a silver openwork hair crown, a dark blue hairband, light-colored layered Hanfu, a semi-transparent blue outer robe, a dark blue waist belt, silver floral buckles, and long tassels. Figure 1 serves as a reference for shot composition and pacing. 2K 16:9 Chinese-style 3D, cinematic Xianxia (fantasy martial arts) quality, strong sense of passion, solemnity, and destiny. Characters are only shown in close-ups or extreme close-ups; distant shots only use back views, side views, or environmental shots."
  },
  "callback_url": "CALLBACK_URL"
}')
JOB_ID=$(echo "$response" | grep -o '"job_id": *"[^"]*"' | sed 's/"job_id": *//; s/"//g')

# Step 2: Poll for results
curl --request GET \
  --url "https://api.shortapi.ai/api/v1/job/query?id=$JOB_ID" \
  --header "Authorization: Bearer $SHORTAPI_KEY"
```

### JavaScript (Fetch API)
```javascript
// Step 1: Create a job
const response = await fetch(`https://api.shortapi.ai/api/v1/job/create`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${SHORTAPI_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "minimax/h3-max/reference-to-video",
    "args": {
      "prompt": "Figure 2 serves as a reference for fixed characters, maintaining consistent elements such as black half-up long hair, a silver openwork hair crown, a dark blue hairband, light-colored layered Hanfu, a semi-transparent blue outer robe, a dark blue waist belt, silver floral buckles, and long tassels. Figure 1 serves as a reference for shot composition and pacing. 2K 16:9 Chinese-style 3D, cinematic Xianxia (fantasy martial arts) quality, strong sense of passion, solemnity, and destiny. Characters are only shown in close-ups or extreme close-ups; distant shots only use back views, side views, or environmental shots."
    },
    "callback_url": "CALLBACK_URL"
})
});
const data = await response.json();
const JOB_ID = data.job_id;

// Step 2: Poll for results
const result = await fetch(`https://api.shortapi.ai/api/v1/job/query?id=${JOB_ID}`, {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${SHORTAPI_KEY}`
  }
});
const resultData = await result.json();
console.log(resultData);
```

### Python (Requests)
```python
import requests

# Step 1: Create a job
url = "https://api.shortapi.ai/api/v1/job/create"
payload = {
  "model": "minimax/h3-max/reference-to-video",
  "args": {
    "prompt": "Figure 2 serves as a reference for fixed characters, maintaining consistent elements such as black half-up long hair, a silver openwork hair crown, a dark blue hairband, light-colored layered Hanfu, a semi-transparent blue outer robe, a dark blue waist belt, silver floral buckles, and long tassels. Figure 1 serves as a reference for shot composition and pacing. 2K 16:9 Chinese-style 3D, cinematic Xianxia (fantasy martial arts) quality, strong sense of passion, solemnity, and destiny. Characters are only shown in close-ups or extreme close-ups; distant shots only use back views, side views, or environmental shots."
  },
  "callback_url": "CALLBACK_URL"
}
headers = {
    "Authorization": f"Bearer {SHORTAPI_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()
JOB_ID = data.get("job_id")

# Step 2: Poll for results
result_url = f"https://api.shortapi.ai/api/v1/job/query?id={JOB_ID}"
result = requests.get(result_url, headers={"Authorization": f"Bearer {SHORTAPI_KEY}"})
print(result.json())
```