# H3 Max Reference to Video API

> Uzalishaji wa video wa H3 Max unaodumisha uwiano wa wahusika kwa kutumia picha, video na klipu za sauti za marejeleo

Huzalisha video ikiongozwa na vipengee vya marejeleo: hadi picha 9, video 3 na klipu za sauti 3, zikiwa faili zisizozidi 12 kwa jumla. Kidokezo huzitaja kama Image 1, Video 1, Audio 1 na kuendelea. Fremu ya kwanza, ya kati (`middle_image_url` katika `middle_frame_time`) na ya mwisho za hiari huweka mwanzo, kati na mwisho. `duration` ni sekunde 0.92 hadi 15, na `aspect_ratio` inaweza kuwa 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/sw/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 | Maagizo ya uzalishaji wa video yenye marejeleo yaliyotambuliwa kwa aina ya nyenzo na nafasi katika kila orodha ya marejeleo, yakitumia lebo kama Audio 1, Video 1, Image 1, Image 2, na kuendelea. |
| `reference_image_urls` | `images` | array of image URL | no |  | ≤ 9 items | URL za picha za marejeleo ya mhusika au mtindo, zinazoshiriki kikomo cha faili 12 na marejeleo yote ya video na sauti. Tambua picha hizi kwenye kidokezo kwa nafasi ya orodha kwa kutumia Image 1, Image 2, na lebo zinazofuata. |
| `reference_video_urls` |  | array of video URL | no |  | ≤ 3 items | URL za video za marejeleo ya mwendo au vingine, zinazotambuliwa kwenye kidokezo kwa nafasi ya orodha kwa kutumia Video 1, Video 2, na lebo zinazofuata. Kikomo cha pamoja cha picha, video na sauti ni faili 12; klipu za video lazima kila moja idumu sekunde 2–15 na jumla isizidi sekunde 15. |
| `reference_audio_urls` |  | array of audio URL | no |  | ≤ 3 items | Toa sauti ya marejeleo kama URL na tambua klipu kwenye kidokezo kwa kutumia Audio 1, Audio 2, na lebo zinazofuata. Kila klipu lazima idumu sekunde 2–15, huku jumla ya sauti isizidi sekunde 15. Aina yoyote ya marejeleo ya picha, video na sauti inaweza kutolewa peke yake au kwa pamoja, kwa kikomo cha pamoja cha faili 12. |
| `image_url` | `image` | string (image URL) \| null | no |  | ≥ 1 characters | URL ya hiari ya picha inayobainisha fremu halisi ya mwanzo na kuamua turubai ya tokeo. Vipengee vya marejeleo hudumisha uthabiti wa mhusika. |
| `middle_image_url` |  | string (image URL) \| null | no |  | ≥ 1 characters | Picha ya hiari ya mwongozo kwa middle_frame_time, inayopatikana tu kwa uzalishaji asilia wa 480P au 768P na picha ya mwanzo na ya mwisho zote zikitolewa. |
| `middle_frame_time` |  | number \| null | no |  | > 0, < 15 | Muda wa kuweka picha ya kati, unaoweza kutumika tu pamoja na middle_image_url na ukiwa katika nafasi zilizo ndani kabisa ya fremu ya kwanza na ya mwisho ya video iliyoombwa. Toa sekunde zilizopita tangu mwanzo; thamani huzungushwa hadi fremu ya karibu zaidi ya 24 fps. |
| `end_image_url` | `end_image` | string (image URL) \| null | no |  | ≥ 1 characters | URL ya hiari ya picha ya mwisho inayoweka fremu halisi ya mwisho ya video kuwa picha iliyotolewa. |
| `duration` |  | number | no | `5` | 0.92 – 15 | Muda ulioombwa kwa sekunde, unaoruhusu urefu halisi wa video kuzidi ombi hilo kwa takriban 0.7 s. |
| `resolution` |  | enum (string) | no | `768P` | `480P`, `768P`, `1080P` | Chaguo la mwonekano wa uzalishaji: 1080P huhitaji uboreshaji wa latent wa nyenzo iliyozalishwa kiasili katika 768P, badala ya uzalishaji kiasili katika mwonekano uliochaguliwa. |
| `seed` |  | integer \| null | no |  |  | Seed ya uzalishaji wa nasibu; ikiachwa, huchaguliwa bila mpangilio. |
| `enable_safety_checker` |  | boolean | no | `true` |  | Uanzishaji wa kikagua usalama; true huanzisha ukaguzi. |
| `prompt_expansion_mode` |  | string | yes | `balanced` |  | Juhudi za kuandika upya kidokezo kabla ya uzalishaji: 'quality' hutengeneza kidokezo tajiri zaidi kwa takriban 30s, huku 'balanced' ikirejesha matokeo kwa takriban sekunde moja. Chagua 'disabled' kuacha upanuzi wa kidokezo. |
| `aspect_ratio` |  | enum (string) | no | `adaptive` | `adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` | Uwiano wa picha wa video ya tokeo. |
| `reference_conditions` |  | array of object {type, url} | no |  | ≤ 12 items | Orodha ya marejeleo inayotolewa badala ya reference_*_urls, kamwe si pamoja nazo. Mpangilio kati ya modali una maana, hivyo mfuatano huhifadhiwa wakati wote wa uchakataji. |
| `reference_conditions[].type` |  | enum (string) | yes |  | `image`, `video`, `audio` | Modali ya rejeleo; mpangilio kati ya modali kwenye orodha una maana. |
| `reference_conditions[].url` |  | string | yes |  | ≥ 1 characters | URL ya nyenzo ya rejeleo. |

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 iliyotolewa na modeli. |
| `expanded_prompt` | string \| null | Kidokezo kilichopanuliwa na kuandaliwa kwa modeli, au null ikiwa hakuna maandishi yaliyopanuliwa. Hali za null ni upanuzi uliozimwa, upanuzi ambao haukubadilisha chochote, na upanuzi ulioshughulikiwa ndani na API iliyopangishwa ya modeli. |
| `seed` | integer | Seed ya msingi inayotumika kuzalisha tena tokeo lililotengenezwa. |
| `timings` | object \| null | Vipimo vya muda vilivyoonyeshwa kwa sekunde, vinavyopatikana tu kwenye njia zinazoripoti muda wa backend; vinginevyo ni null. Ingizo la 'inference' hupima muda ambao uondoaji wa kelele wa DiT ulichukua kwenye backend ya GPU. |

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