# H3 Max Reference to Video API

> H3 Max na pagbuo ng video na pinananatiling pare-pareho ang mga subject gamit ang reference larawan, video at audio clip

Gumagawa ng video na ginagabayan ng reference asset: hanggang 9 larawan, 3 video at 3 audio clip, na may kabuuang hanggang 12 file. Tinutukoy ng prompt ang mga ito bilang Image 1, Video 1, Audio 1 at iba pa. Maaaring magtakda ang opsyonal na una, gitna (`middle_image_url` sa `middle_frame_time`) at huling frame ng simula, gitna at wakas. Ang `duration` ay 0.92 hanggang 15 segundo, at maaaring adaptive ang `aspect_ratio`.

- Model id: `minimax/h3-max/reference-to-video`
- Made by: MiniMax
- Category: Reference to Video
- Output: video
- Price per second of your output video: from $0.05 / second of output video (cheapest run $0.05 (50 API credits))
- Run: `POST https://api.doitong.ru/v1/run/minimax/h3-max/reference-to-video`
- Quote: `POST https://api.doitong.ru/v1/quote/minimax/h3-max/reference-to-video`
- Docs page: https://doitong.com/fil/developers/models/minimax/h3-max/reference-to-video

## Pricing

Price: **from $0.05 / second of output video** (the lowest tier; the quote prices your exact input). Price per second of your output video: the input files are measured before the run (length, resolution, frame rate). The quote measures the same files and is exactly what the run charges.

Price by tier:

- 480P: $0.05 / second of output video
- 768P: $0.08 / second of output video
- 1080P: $0.16 / second of output video

The full example input below costs $0.40 = 400 API credits (5 s output video × $0.08 (768P)).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). `POST https://api.doitong.ru/v1/quote/minimax/h3-max/reference-to-video` with the same JSON body returns the exact price for that input; the quote is exactly what a run charges. Invalid input is never charged and failed or canceled requests are refunded automatically.

## Input parameters

Send either the canonical name or the native field name (not both). Canonical names are the same across models.

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `prompt` |  | string | yes |  | 1 – 50000 characters | Mga instruction sa pagbuo ng video na may mga reference na tinutukoy ayon sa uri ng asset at posisyon sa bawat reference list, gamit ang mga label gaya ng Audio 1, Video 1, Image 1, Image 2, at iba pa. |
| `reference_image_urls` | `images` | array of image URL | no |  | ≤ 9 items | Mga URL ng larawan reference para sa subject o style, na may pinagsasaluhang maximum na 12 file kasama ang lahat ng reference sa video at audio. Tukuyin ang mga larawan na ito sa prompt ayon sa posisyon sa list gamit ang Larawan 1, Larawan 2, at mga kasunod na label. |
| `reference_video_urls` |  | array of video URL | no |  | ≤ 3 items | Mga URL ng reference video para sa motion o iba pang gamit, na tinutukoy sa prompt ayon sa posisyon sa list gamit ang Video 1, Video 2, at mga kasunod na label. Ang pinagsasaluhang allowance para sa larawan, video, at audio reference ay 12 file; dapat tumagal ang bawat video clip nang 2–15 segundo at hindi hihigit sa 15 segundo ang kabuuan. |
| `reference_audio_urls` |  | array of audio URL | no |  | ≤ 3 items | Magbigay ng reference audio bilang mga URL at tukuyin ang mga clip sa prompt gamit ang Audio 1, Audio 2, at mga kasunod na label. Dapat tumagal ang bawat clip nang 2–15 segundo, at hindi hihigit sa 15 segundo ang kabuuang audio. Maaaring ibigay nang mag-isa o pagsamahin ang alinman sa larawan, video, at audio reference type, ayon sa pinagsasaluhang maximum na 12 file. |
| `image_url` | `image` | string (image URL) \| null | no |  | ≥ 1 characters | Opsyonal na larawan URL na tumutukoy sa eksaktong pambungad na frame at output canvas. Pinananatili ng mga reference asset ang consistency ng subject. |
| `middle_image_url` |  | string (image URL) \| null | no |  | ≥ 1 characters | Opsyonal na guiding larawan para sa middle_frame_time, available lamang sa native 480P o 768P na pagbuo at kapag parehong may ibinigay na panimulang larawan at pangwakas na larawan. |
| `middle_frame_time` |  | number \| null | no |  | > 0, < 15 | Oras ng paglalagay ng middle larawan, magagamit lamang kasama ng middle_image_url at limitado sa mga posisyong mahigpit na nasa loob ng unang at huling frame ng hinihinging video. Magbigay ng mga segundong lumipas mula sa simula; niroround ang value sa pinakamalapit na 24 fps frame. |
| `end_image_url` | `end_image` | string (image URL) \| null | no |  | ≥ 1 characters | Opsyonal na URL ng pangwakas na larawan na nagtatakda sa eksaktong ending frame ng video bilang ibinigay na larawan. |
| `duration` |  | number | no | `5` | 0.92 – 15 | Hinihinging tagal sa segundo, na nagpapahintulot sa aktuwal na haba ng video na lumampas nang humigit-kumulang 0.7 s sa kahilingan. |
| `resolution` |  | enum (string) | no | `768P` | `480P`, `768P`, `1080P` | Pagpili ng resolution ng pagbuo: nangangailangan ang 1080P ng latent refinement ng materyal na native na nabuo sa 768P, sa halip na native na pagbuo sa piniling resolution. |
| `seed` |  | integer \| null | no |  |  | Seed para sa random na pagbuo; kung hindi ibinigay, random na pipili ng isa. |
| `enable_safety_checker` |  | boolean | no | `true` |  | Pag-activate ng safety checker; pinapagana ng true ang checking. |
| `prompt_expansion_mode` |  | string | yes | `balanced` |  | Pagsisikap sa muling pagsulat ng prompt bago ang pagbuo: ang 'quality' ay bumubuo ng mas detalyadong prompt sa loob ng humigit-kumulang 30s, habang ang 'balanced' ay nagbabalik sa loob ng humigit-kumulang isang segundo. Piliin ang 'disabled' upang laktawan ang pagpapalawak ng prompt. |
| `aspect_ratio` |  | enum (string) | no | `adaptive` | `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` | Aspect ratio ng output na video. |
| `reference_conditions` |  | array of object {type, url} | no |  | ≤ 12 items | Reference list na ibinibigay bilang alternatibo sa reference_*_urls, hindi kailanman kasabay ng mga ito. Mahalaga ang pagkakasunod-sunod sa iba't ibang modality, kaya pinananatili ang sequence sa buong processing. |
| `reference_conditions[].type` |  | enum (string) | yes |  | `image`, `video`, `audio` | Modality ng reference; mahalaga ang pagkakasunod-sunod ng mga modality sa list. |
| `reference_conditions[].url` |  | string | yes |  | ≥ 1 characters | URL ng reference media. |

File parameters (`images`, `reference_video_urls`, `reference_audio_urls`, `image`, `middle_image_url`, `end_image`) take a public `https://` URL, a `data:` URI up to 10 MB, or the `file_url` of an upload from `POST /files`.

## Example input

Required parameters only:

```json
{
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
  "prompt_expansion_mode": "balanced"
}
```

A fuller example:

```json
{
  "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
  "prompt_expansion_mode": "balanced"
}
```

## Run it

Set `DOITONG_API_KEY` to a key from https://doitong.com/developers/dashboard#keys. `?wait=20` returns the finished request in the same call when it is ready within 20 seconds; otherwise poll `GET /requests/{id}` (it also accepts `?wait=`), or pass `webhook_url`.

### curl

```bash
# Run the model; wait up to 20 s for the finished result in the same call
curl -X POST "https://api.doitong.ru/v1/run/minimax/h3-max/reference-to-video?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
    "prompt_expansion_mode": "balanced"
  }'

# Still "queued" or "running"? Poll with the id from the response:
curl "https://api.doitong.ru/v1/requests/REQUEST_ID?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"
```

### JavaScript

```javascript
const API = "https://api.doitong.ru/v1";
const headers = {
  "Authorization": "Bearer " + process.env.DOITONG_API_KEY,
  "Content-Type": "application/json",
};

// Run the model; wait up to 20 s for the finished result in the same call
let res = await fetch(API + "/run/minimax/h3-max/reference-to-video?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
    "prompt_expansion_mode": "balanced"
  }),
});
let request = await res.json();
if (!res.ok) throw new Error(request.error.code + ": " + request.error.message);

// Not finished yet: long-poll until it is
while (request.status === "queued" || request.status === "running") {
  res = await fetch(API + "/requests/" + request.id + "?wait=20", { headers });
  request = await res.json();
}
if (request.status !== "succeeded") throw new Error(JSON.stringify(request.error));
console.log(request.outputs.map((o) => o.url), request.cost.credits + " API credits ($" + request.cost.usd + ")");
```

### Python

```python
import os
import requests

API = "https://api.doitong.ru/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
    "prompt_expansion_mode": "balanced",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/minimax/h3-max/reference-to-video", params={"wait": 20}, json=payload, headers=headers)
request = r.json()
if not r.ok:
    raise RuntimeError(request["error"]["code"] + ": " + request["error"]["message"])

# Not finished yet: long-poll until it is
while request["status"] in ("queued", "running"):
    request = requests.get(API + "/requests/" + request["id"], params={"wait": 20}, headers=headers).json()
if request["status"] != "succeeded":
    raise RuntimeError(request["error"])
print([o["url"] for o in request["outputs"]], request["cost"]["credits"], "API credits", "$" + request["cost"]["usd"])
```

### MCP

The MCP server at `https://api.doitong.ru/v1/mcp` exposes the tools `search_models`, `get_model`, `quote`, `run`, `get_request`, `cancel_request`, `list_requests`, `create_upload` and `get_account`. A `run` call for this model:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run",
    "arguments": {
      "model_id": "minimax/h3-max/reference-to-video",
      "input": {
        "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
        "prompt_expansion_mode": "balanced"
      },
      "wait_seconds": 20
    }
  }
}
```

## Response

Every call returns a request object. `status` is one of `queued`, `running`, `succeeded`, `failed`, `canceled`. `outputs` lists the generated files with URLs on our storage (kept forever, or 7 days with `?storage=temporary`; `storage` says which); `output` is the model's own result object with the same URLs.

```json
{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "minimax/h3-max/reference-to-video",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:02Z",
  "completed_at": "2026-10-20T12:00:09Z",
  "queue_position": null,
  "cost": {
    "credits": 400,
    "usd": "0.40",
    "charged": 400,
    "refunded": 0
  },
  "input": {
    "prompt": "A red fox trots through fresh snow at sunrise, soft golden light, shallow depth of field",
    "prompt_expansion_mode": "balanced"
  },
  "output": {
    "video": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.mp4",
      "content_type": "video/mp4",
      "file_name": "0-output.mp4",
      "file_size": 1843200
    },
    "expanded_prompt": "string",
    "seed": 42,
    "timings": {}
  },
  "outputs": [
    {
      "type": "video",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.mp4",
      "content_type": "video/mp4",
      "file_size": 1843200,
      "width": 1280,
      "height": 720,
      "duration": 5,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.ru/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `video` | object {url, content_type, file_name, file_size} | Video na ginawa ng modelo. |
| `expanded_prompt` | string \| null | Pinalawak na prompt na handa para sa modelo, o null kung walang available na pinalawak na text. Kasama sa mga null case ang disabled na pagpapalawak, pagpapalawak na walang binago, at pagpapalawak na pinangasiwaan sa loob ng hosted API ng modelo. |
| `seed` | integer | Base seed na ginagamit upang ulitin ang nabuong resulta. |
| `timings` | object \| null | Mga sukat ng oras na ipinapahayag sa segundo, na available lamang sa mga route na nag-uulat ng backend timings; kung hindi, null. Sinusukat ng entry na 'inference' kung gaano katagal ang DiT denoising sa GPU backend. |

## Related models

- [MiniMax H3 Max Text to Video](https://doitong.com/developers/models/minimax/h3-max/text-to-video.md) (`minimax/h3-max/text-to-video`): from $0.0325 / second of output video
- [H3 Max Camera Controls](https://doitong.com/developers/models/minimax/h3-max/camera-controls.md) (`minimax/h3-max/camera-controls`): from $0.0325 / second
- [H3 Max Image to Video](https://doitong.com/developers/models/minimax/h3-max/image-to-video.md) (`minimax/h3-max/image-to-video`): from $0.0325 / second of output video
- [H3 Max](https://doitong.com/developers/models/minimax/h3-max/insert-video.md) (`minimax/h3-max/insert-video`): from $0.05 / second
- [H3 Max Extend Video](https://doitong.com/developers/models/minimax/h3-max/extend-video.md) (`minimax/h3-max/extend-video`): from $0.05 / second of output video
- [H3 Max Recast](https://doitong.com/developers/models/minimax/h3-max/recast.md) (`minimax/h3-max/recast`): from $0.30 / second of input video
- [H3 Max Reframe](https://doitong.com/developers/models/minimax/h3-max/reframe-video.md) (`minimax/h3-max/reframe-video`): from $0.05 / second of input video
- [H3 Max Relight](https://doitong.com/developers/models/minimax/h3-max/relight.md) (`minimax/h3-max/relight`): from $0.05 / second of input video

## Links

- HTML page: https://doitong.com/developers/models/minimax/h3-max/reference-to-video
- All models and guides for AI agents: https://doitong.com/developers/llms.txt
- OpenAPI 3.1 with this model's typed request body: https://doitong.com/developers/openapi.json?model=minimax/h3-max/reference-to-video
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.ru/v1/models/minimax/h3-max/reference-to-video