# MiniMax H3 Reference to Video LoRA Trainer API

> Bộ huấn luyện LoRA cho video có điều kiện hóa theo tham chiếu, với khả năng khởi động tiếp từ LoRA trước đó

Huấn luyện LoRA trên tệp zip chứa các đoạn video chủ thể để đầu vào tham chiếu định hướng việc tạo video. `reference_conditioning_p` thiết lập tần suất sử dụng tham chiếu trong quá trình huấn luyện, còn `resume_from_lora_url` tiếp tục từ LoRA đã huấn luyện trước đó. Các tùy chọn khác gồm `rank`, `number_of_steps`, `number_of_frames`, `frame_rate` và `aspect_ratio`. Trả về trọng số và một tệp cấu hình.

- Model id: `minimax/h3/ref2va/trainer`
- Made by: MiniMax
- Category: Training
- Output: file
- Price: $0.015 / step (cheapest run $30.00 (30000 API credits))
- Run: `POST https://api.doitong.com/v1/run/minimax/h3/ref2va/trainer`
- Quote: `POST https://api.doitong.com/v1/quote/minimax/h3/ref2va/trainer`
- Docs page: https://doitong.com/vi/developers/models/minimax/h3/ref2va/trainer

## Pricing

Price: **$0.015 / step**. Billed per training step (`number_of_steps`).

The full example input below costs $30.00 = 30000 API credits (2000 steps × 15 API credits).

Prices are the upstream price in USD, paid from the API balance in API credits (1000 API credits = 1 USD). `POST https://api.doitong.com/v1/quote/minimax/h3/ref2va/trainer` 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

| Parameter | Canonical name | Type | Required | Default | Allowed values / range | Description |
|---|---|---|---|---|---|---|
| `training_data_url` |  | string | yes |  |  | URL ZIP chứa video huấn luyện chủ thể; bộ dữ liệu chỉ có hình ảnh và kho huấn luyện trộn hình ảnh/video sẽ bị từ chối, vì vậy hình ảnh phải được cung cấp dưới dạng sidecar tham chiếu. Tiện ích tùy chọn dùng chung tên cơ sở với từng clip: chú thích như `clip01.txt` và các tham chiếu theo thứ tự từ `ref_1` đến `ref_4`, có tên `clip01.ref_1.<ext>` đến `clip01.ref_4.<ext>`; nếu không có sidecar tham chiếu, một khung hình từ clip sẽ cung cấp tham chiếu của chính nó. `<ext>` xác định phương thức tham chiếu: hình ảnh (.png/.jpg/.jpeg), âm thanh (.wav/.mp3/.flac/.m4a/.ogg/.aac) hoặc video (.mp4/.mov/.avi/.mkv/.webm), trong đó nhạc nền cũng trở thành tham chiếu âm thanh. Clip huấn luyện hỗ trợ .mp4, .mov, .avi và .mkv; nên có ít nhất 10 clip, càng nhiều càng tốt. |
| `rank` |  | enum (integer) | no | `32` | `8`, `16`, `32`, `64`, `128` | Cấp bậc thích ứng LoRA, đánh đổi mức tiêu thụ bộ nhớ tăng lên để có năng lực lớn hơn khi thiết lập tăng. |
| `number_of_steps` |  | integer | no | `2000` | 1 – 15,000 | Tổng số bước huấn luyện. |
| `learning_rate` |  | number | no | `0.0002` | 0.000001 – 1 | Tốc độ học tối ưu hóa, cân bằng giữa khả năng tăng tốc huấn luyện và nguy cơ overfitting khi tăng giá trị. |
| `number_of_frames` |  | integer | no | `73` | 22 – 124 | Số khung hình cho mỗi mẫu huấn luyện; chia cho 17 phải dư 5. Ví dụ gồm 22, 39, 56, 73, 90, 107 và 124. |
| `frame_rate` |  | integer | no | `24` | 8 – 60 | Tốc độ khung hình video mục tiêu, được đo bằng khung hình trên giây. |
| `resolution` |  | enum (string) | no | `medium` | `low`, `medium`, `high` | Độ phân giải huấn luyện. Tăng độ phân giải sẽ tăng yêu cầu bộ nhớ. |
| `aspect_ratio` |  | enum (string) | no | `16:9` | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16` | Chọn tỷ lệ khung hình huấn luyện từ cùng tập hợp có trong MiniMax H3 API. |
| `trigger_phrase` |  | string | no | `` |  | Cụm từ kích hoạt kiểu LoRA, được chèn vào đầu chú thích trong quá trình huấn luyện. |
| `reference_conditioning_p` |  | number | no | `0.9` | 0 – 1 | Đặt tần suất huấn luyện sử dụng điều kiện hóa bằng hình ảnh tham chiếu so với huấn luyện text-to-video-audio không điều kiện hóa. Phần xác suất còn lại dành cho mục tiêu không điều kiện hóa để duy trì tạo sinh ổn định chỉ từ lời nhắc. |
| `resume_from_lora_url` |  | string \| null | no |  |  | URL để huấn luyện khởi động từ .safetensors LoRA đã được trainer này tạo trước đó, tiếp theo là số bước huấn luyện bổ sung number_of_steps. Không khôi phục gì ngoài trọng số bộ chuyển đổi: cả quá trình tối ưu hóa và lập lịch tốc độ học đều bắt đầu lại. |
| `auto_scale_input` |  | boolean | no | `false` |  | Liệu fps đích và số khung hình có được khớp bằng cách tự động điều chỉnh video hay không; true bật điều chỉnh này. |
| `split_input_into_scenes` |  | boolean | no | `true` |  | Bật tách cảnh cho video dài hơn ngưỡng thời lượng, loại bỏ sidecar tham chiếu khỏi mọi clip bị tách. |
| `split_input_duration_threshold` |  | number | no | `30` | 1 – 60 | Điều kiện tách cảnh được biểu thị bằng thời lượng theo giây: chỉ video dài hơn ngưỡng mới được tách. |
| `debug_dataset` |  | boolean | no | `false` |  | Tùy chọn tải kho lưu trữ để kiểm tra tiền xử lý trước khi bắt đầu huấn luyện đầy đủ. Khi bật, trainer đóng gói bộ dữ liệu đã xử lý để bạn kiểm tra thủ công chú thích, hình ảnh tham chiếu, video và hình ảnh. |
| `strict_dataset` |  | boolean | no | `false` |  | Xử lý nghiêm ngặt các vấn đề tiền xử lý vốn sẽ được ghi nhật ký và giải quyết bằng phương án dự phòng đã tài liệu hóa. Khi bật, hệ thống từ chối chú thích cần lời nhắc trống, sidecar tham chiếu bị thiếu và video có âm thanh không thể đọc thay vì cho phép các phương án dự phòng đó. |

## Example input

Required parameters only:

```json
{
  "training_data_url": "https://example.com/your-file.zip"
}
```

A fuller example:

```json
{
  "training_data_url": "https://example.com/your-file.zip"
}
```

## 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.com/v1/run/minimax/h3/ref2va/trainer?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "training_data_url": "https://example.com/your-file.zip"
  }'

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

### JavaScript

```javascript
const API = "https://api.doitong.com/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/ref2va/trainer?wait=20", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "training_data_url": "https://example.com/your-file.zip"
  }),
});
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.com/v1"
headers = {"Authorization": "Bearer " + os.environ["DOITONG_API_KEY"]}

payload = {
    "training_data_url": "https://example.com/your-file.zip",
}

# Run the model; wait up to 20 s for the finished result in the same call
r = requests.post(API + "/run/minimax/h3/ref2va/trainer", 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.com/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/ref2va/trainer",
      "input": {
        "training_data_url": "https://example.com/your-file.zip"
      },
      "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/ref2va/trainer",
  "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": 30000,
    "usd": "30.00",
    "charged": 30000,
    "refunded": 0
  },
  "input": {
    "training_data_url": "https://example.com/your-file.zip"
  },
  "output": {
    "lora_file": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    },
    "config_file": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    },
    "debug_dataset": {
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_name": "0-output.jpeg",
      "file_size": 1843200
    }
  },
  "outputs": [
    {
      "type": "file",
      "url": "https://content.doitong.com/dev-api/2026/10/20/req_8k2m4q7x1z9c3v5b6n0p2r4t/0-output.jpeg",
      "content_type": "image/jpeg",
      "file_size": 1843200,
      "stored": true
    }
  ],
  "error": null,
  "metrics": {
    "inference_seconds": 6.8
  },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}
```

### Output fields (`output`)

| Field | Type | Description |
|---|---|---|
| `lora_file` | object {url, content_type, file_name, file_size} | URL của trọng số LoRA đã huấn luyện ở định dạng .safetensors. |
| `config_file` | object {url, content_type, file_name, file_size} | Cấu hình thiết lập điểm cuối suy luận. |
| `debug_dataset` | object {url, content_type, file_name, file_size} \| null | Chỉ khả dụng cho các yêu cầu bật `debug_dataset`, kho lưu trữ có thể tải xuống này chứa dữ liệu huấn luyện sau tiền xử lý. |

## Related models

- [MiniMax H3 First Last Frame LoRA Trainer](https://doitong.com/developers/models/minimax/h3/flf2v/trainer.md) (`minimax/h3/flf2v/trainer`): $0.01 / step
- [MiniMax H3 Image to Video Audio LoRA Trainer](https://doitong.com/developers/models/minimax/h3/i2v/trainer.md) (`minimax/h3/i2v/trainer`): $0.01 / step
- [MiniMax H3 Text to Video LoRA Trainer](https://doitong.com/developers/models/minimax/h3/t2v/trainer.md) (`minimax/h3/t2v/trainer`): $0.005 / step
- [ERNIE-Image Trainer](https://doitong.com/developers/models/ernie-image-trainer.md) (`ernie-image-trainer`): $0.0012 / step
- [FLUX 2 \[klein\] 9b Base Trainer](https://doitong.com/developers/models/flux-2-klein-9b-base-trainer.md) (`flux-2-klein-9b-base-trainer`): $0.0043 / step
- [Flux 2 Klein 9B Base Trainer](https://doitong.com/developers/models/flux-2-klein-9b-base-trainer/edit.md) (`flux-2-klein-9b-base-trainer/edit`): $0.0139 / step
- [FLUX 2 Trainer](https://doitong.com/developers/models/flux-2-trainer.md) (`flux-2-trainer`): $0.0064 / step
- [FLUX 2 Trainer Edit](https://doitong.com/developers/models/flux-2-trainer/edit.md) (`flux-2-trainer/edit`): $0.0389 / step

## Links

- HTML page: https://doitong.com/developers/models/minimax/h3/ref2va/trainer
- 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/ref2va/trainer
- Errors: https://doitong.com/developers/docs/errors
- Model details as JSON: https://api.doitong.com/v1/models/minimax/h3/ref2va/trainer