# H3 Max Reference to Video API

> H3 Max myndbandsgerð sem heldur myndefni samræmdu með viðmiðunarmyndum, myndböndum og hljóðbú​​tum

Myndar myndband með leiðsögn frá viðmiðunarefnum: allt að 9 myndir, 3 myndbönd og 3 hljóðbútum, að hámarki 12 skrár samtals. Kvaðningin vísar til þeirra sem Image 1, Video 1, Audio 1 og svo framvegis. Valfrjálsir fyrsti, miðju- (`middle_image_url` við `middle_frame_time`) og síðasti rammi festa upphaf, miðju og endi. `duration` er 0.92 til 15 sekúndur og `aspect_ratio` getur verið adaptive.

- 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/is/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 | Leiðbeiningar fyrir myndbandsgerð með tilvísunum sem eru auðkenndar eftir gerð og staðsetningu í hverjum tilvísanalista, með merkjum á borð við Audio 1, Video 1, Image 1, Image 2 og svo framvegis. |
| `reference_image_urls` | `images` | array of image URL | no |  | ≤ 9 items | Slóðir á tilvísunarmyndir fyrir myndefni eða stíl, með sameiginlegu hámarki 12 skráa með öllum myndbands- og hljóðtilvísunum. Auðkenndu þessar myndir í kvaðningunni eftir stöðu í listanum með Image 1, Image 2 og síðari merkjum. |
| `reference_video_urls` |  | array of video URL | no |  | ≤ 3 items | Slóðir á tilvísunarmyndbönd fyrir hreyfingu eða annað, auðkennd eftir stöðu í kvaðningunni með Video 1, Video 2 og síðari merkjum. Sameiginlegt hámark fyrir myndir, myndbönd og hljóð er 12 skrár; hvert myndband verður að vera 2–15 sekúndur og samanlagt að hámarki 15 sekúndur. |
| `reference_audio_urls` |  | array of audio URL | no |  | ≤ 3 items | Gefðu upp tilvísunarhljóð sem slóðir og auðkenndu bútana í kvaðningunni með Audio 1, Audio 2 og síðari merkjum. Hver bútur verður að vera 2–15 sekúndur og heildarhljóðið að hámarki 15 sekúndur. Hægt er að gefa upp hvaða gerð tilvísunar sem er ein sér eða saman, með sameiginlegu hámarki 12 skráa. |
| `image_url` | `image` | string (image URL) \| null | no |  | ≥ 1 characters | Valfrjáls myndaslóð sem skilgreinir nákvæman upphafsramma og úttakssvæði. Tilvísunarefni viðheldur samræmi myndefnis. |
| `middle_image_url` |  | string (image URL) \| null | no |  | ≥ 1 characters | Valfrjáls leiðbeinandi mynd fyrir middle_frame_time, aðeins tiltæk með upprunalegri 480P- eða 768P-efnisgerð og þegar bæði upphafs- og lokamynd eru gefnar upp. |
| `middle_frame_time` |  | number \| null | no |  | > 0, < 15 | Tími fyrir staðsetningu miðmyndar, aðeins nothæfur með middle_image_url og takmarkaður við stöður strangt innan fyrsta og síðasta ramma umbeðins myndbands. Gefðu upp liðnar sekúndur frá upphafi; gildið er námundað að næsta ramma við 24 fps. |
| `end_image_url` | `end_image` | string (image URL) \| null | no |  | ≥ 1 characters | Valfrjáls lokamyndaslóð sem festir nákvæman lokaramma myndbandsins við uppgefna mynd. |
| `duration` |  | number | no | `5` | 0.92 – 15 | Umbeðin lengd í sekúndum, en raunverulegt myndband getur orðið allt að um 0.7 s lengra. |
| `resolution` |  | enum (string) | no | `768P` | `480P`, `768P`, `1080P` | Val á upplausn efnisgerðar: 1080P krefst duldra betrumbóta á efni sem er upprunalega gert í 768P, í stað upprunalegrar efnisgerðar í valinni upplausn. |
| `seed` |  | integer \| null | no |  |  | Sáð fyrir slembna efnisgerð; ef það er sleppt er eitt valið af handahófi. |
| `enable_safety_checker` |  | boolean | no | `true` |  | Virkjun öryggisathugunar; true virkjar athugun. |
| `prompt_expansion_mode` |  | string | yes | `balanced` |  | Vinnsla við endurskrifun kvaðningar fyrir efnisgerð: 'quality' þróar ríkari kvaðningu í allt að um 30 s, en 'balanced' skilar niðurstöðu á um það bil sekúndu. Veldu 'disabled' til að sleppa útvíkkun kvaðningar. |
| `aspect_ratio` |  | enum (string) | no | `adaptive` | `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` | Stærðarhlutfall úttakmyndbandsins. |
| `reference_conditions` |  | array of object {type, url} | no |  | ≤ 12 items | Tilvísanalisti sem er gefinn upp í staðinn fyrir reference_*_urls, aldrei samhliða þeim. Röðun milli miðlunargerða skiptir máli og er viðhaldið í allri vinnslunni. |
| `reference_conditions[].type` |  | enum (string) | yes |  | `image`, `video`, `audio` | Miðlunargerð tilvísunar; röðun milli miðlunargerða í listanum skiptir máli. |
| `reference_conditions[].url` |  | string | yes |  | ≥ 1 characters | Slóð tilvísunarmiðils. |

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} | Myndband sem líkanið býr til. |
| `expanded_prompt` | string \| null | Útv\|\|\|\|un kvaðning tilbúin fyrir líkanið, eða null ef enginn útvíkkaður texti er tiltækur. null á við þegar útvíkkun er óvirk, breytir engu eða er meðhöndluð innbyrðis af hýstu API líkaninu. |
| `seed` | integer | Grunnsáð sem er notað til að endurskapa myndaða niðurstöðu. |
| `timings` | object \| null | Tímamælingar gefnar upp í sekúndum, aðeins tiltækar á leiðum sem skila bakendatímum; annars null. 'inference'-færslan mælir hversu lengi DiT-afsuðning tók á GPU-bakenda. |

## 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