# minimax/h3/reference-to-video

> Generate a 2K video using one reference video, optional reference images, and a text prompt.

## Overview

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

## Pricing

$0.131 per second for output video and reference video duration. The first 5 reference images are free; each additional reference image costs $0.040.

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 content. Maximum 2,000 characters.
  - Examples: "An action shot of a black lab swimming..."

- **`reference_video_url`** (`string`, _required_):
  One reference video URL or Base64 video. Supported duration: 2 to 15 seconds.

- **`reference_image_urls`** (`list<string>`, _optional_):
  Optional reference image URLs or Base64 images. Up to 9 images are supported.

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

- **`aspect_ratio`** (`string`, _optional_):
  Output video aspect ratio. Use adaptive to follow the reference video 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/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.",
    "reference_video_url": ""
  },
  "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/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.",
      "reference_video_url": ""
    },
    "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/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.",
    "reference_video_url": ""
  },
  "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())
```