MiniMax Hailuo

Hailuo là dòng tạo video của MiniMax. Một kênh phục vụ hai thế hệ API: MiniMax-H3 và MiniMax-H3-Max dùng API /v2 của MiniMax với mảng content và quyết toán theo giây, còn dòng MiniMax-Hailuo-2.3 dùng API /v1 cũ với giá cố định theo tác vụ (trình bày ở cuối trang).

Tác vụ được gửi, truy vấn và tải xuống qua các endpoint chung mô tả tại Tạo tác vụ và Truy vấn tác vụ. Trang này nói rõ nhà cung cấp này đọc những trường nào, yêu cầu được dựng ra sao và cách tính phí.

Mô hình

ID mô hình	Độ phân giải	Thời lượng (giây nguyên)	Mặc định	Mở rộng prompt
`MiniMax-H3`	`768P`, `2K`	4–15	`768P`, 5 giây	Không
`MiniMax-H3-Max`	`480P`, `768P`	5–15	`768P`, 5 giây	Có

ID mô hình phân biệt hoa thường, hãy ghi đúng như bảng trên. Tài khoản chỉ dùng được những mô hình được định tuyến tới nó, và giá phụ thuộc từng tài khoản; GET /v1/models là danh sách có thẩm quyền cho khóa của bạn.
Chỉ MiniMax-H3-Max nhận extra. Gửi extra tới MiniMax-H3 trả về 400.
Cả hai mô hình đều hỗ trợ văn bản thành video, khung đầu, khung đầu và cuối, cùng ảnh / video / âm thanh tham chiếu.

Tham số yêu cầu

Trường	Kiểu	Bắt buộc	Mặc định	Mô tả
`model`	string	Có	—	ID mô hình từ `GET /v1/models`
`prompt`	string	Có	—	Prompt; rỗng sau khi bỏ khoảng trắng sẽ bị từ chối. Tối đa 7000 ký tự
`resolution`	string	Không	`768P`	Không phân biệt hoa thường; phải là một trong các độ phân giải của mô hình
`duration`	integer	Không	`5`	Số giây nguyên trong phạm vi của mô hình
`seconds`	string	Không	—	Dạng chuỗi của thời lượng; chỉ đọc khi không có `duration` hoặc `duration` là `0`
`ratio`	string	Không	xem bên dưới	Tỷ lệ khung hình
`images`	string[]	Không	—	1 ảnh = khung đầu, 2 ảnh = khung đầu rồi khung cuối. Tối đa 2 ảnh
`image`	string	Không	—	Một ảnh duy nhất; chỉ dùng khi `images` trống
`metadata`	object	Không	—	Tham số của MiniMax, xem phần tiếp theo

Quy tắc ưu tiên:

metadata.resolution, metadata.duration và metadata.ratio ghi đè các trường cùng tên ở cấp cao nhất.
seconds chỉ được đọc khi duration cấp cao nhất không có hoặc bằng 0, và metadata.duration ưu tiên hơn cả hai.
metadata.duration được phân tích như số, nên 5.5 báo invalid duration. Khác với duration cấp cao nhất, 0 ở đây không phải “chưa đặt” mà là ngoài phạm vi. Muốn giữ mặc định thì bỏ hẳn khóa này.
Không hỗ trợ size. size ở cấp cao nhất hoặc metadata.size trả về MiniMax-H3 请使用 resolution(480P/768P/2K),不支持 size; hãy dùng resolution.
Ngoài size, các trường cấp cao nhất mà nhà cung cấp này không đọc (ví dụ generate_audio, input_reference) bị bỏ qua chứ không bị từ chối.

Tham số metadata

Trường	Kiểu	Mô tả
`content`	array	Vật liệu đầu vào, xem Mục content và giới hạn. Không dùng chung với `images` / `image` cấp cao nhất
`resolution`	string	Ghi đè `resolution` cấp cao nhất
`duration`	number	Ghi đè `duration` và `seconds` cấp cao nhất; phải là số nguyên trong phạm vi
`ratio`	string	Ghi đè `ratio` cấp cao nhất
`aigc_watermark`	boolean hoặc string	`true` / `false`. Cũng nhận chuỗi `"true"` / `"false"`, đúng như biểu mẫu multipart gửi đi. Bỏ trống thì upstream quyết định
`extra.prompt_expansion_mode`	string	`disabled`, `balanced` hoặc `quality`. Chỉ `MiniMax-H3-Max`
`size`	—	Bị từ chối với `400`

metadata được giải mã vào cấu trúc có kiểu: sai kiểu JSON ở một trong các khóa trên (ví dụ "duration": "abc", hay content là object) trả về 400 với invalid metadata: ... và không bị tính phí. Các khóa không có trong bảng — seed, callback_url… — bị bỏ qua và không bao giờ tới MiniMax; không có callback nào được gửi, hãy truy vấn để lấy kết quả.

Tỷ lệ khung hình ratio

Giá trị hợp lệ: adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16. Không phân biệt hoa thường.

Dạng yêu cầu	Bỏ trống `ratio`	Quy tắc
Chỉ văn bản (không khung, không tham chiếu)	`16:9`	`adaptive` bị từ chối với `text-to-video does not support ratio adaptive`
Khung đầu, hoặc khung đầu và cuối	`adaptive`	Bị ép thành `adaptive`; giá trị bạn gửi bị bỏ qua và không được kiểm tra
Vật liệu tham chiếu	`adaptive`	Dùng được cả bảy giá trị

Mục content và giới hạn

metadata.content là mảng có thứ tự. Mỗi mục có một type, một trường payload tương ứng với kiểu đó, và role tùy chọn:

`type`	Payload	`role` được phép	Giới hạn
`text`	`text`	không	1, và phải bằng `prompt`
`image_url`	`image_url.url`	`first_frame`	1
`image_url`	`image_url.url`	`last_frame`	1, và cần có `first_frame`
`image_url`	`image_url.url`	`reference_image`	9
`image_url`	`image_url.url`	không	chỉ khi là vật liệu duy nhất
`video_url`	`video_url.url`	`reference_video` (bắt buộc)	3
`audio_url`	`audio_url.url`	`reference_audio` (bắt buộc)	3

{ "type": "image_url", "role": "reference_image", "image_url": { "url": "https://..." } }
{ "type": "video_url", "role": "reference_video", "video_url": { "url": "https://..." } }
{ "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://..." } }

Các quy tắc được kiểm tra trước khi gửi:

Tối đa 12 vật liệu mỗi yêu cầu, trong đó tối đa 9 ảnh tham chiếu, 3 video tham chiếu và 3 âm thanh tham chiếu.
Ảnh khung đầu / khung cuối và vật liệu tham chiếu không được trộn. reference_image, reference_video và reference_audio kết hợp tự do với nhau.
Mục image_url không có role chỉ được phép khi nó là vật liệu duy nhất; khi đó được coi là first_frame.
Nếu content không có mục text, RouteAPI thêm một mục ở đầu mang prompt cấp cao nhất. Nếu có, chỉ được một mục và nội dung phải bằng prompt sau khi bỏ khoảng trắng đầu cuối, nếu không sẽ báo prompt 与 metadata.content 中的 text 冲突.
content và images / image cấp cao nhất loại trừ nhau.
Chỉ trường khớp với type của mục được chuyển tiếp; các khóa thừa bị bỏ.
URL vật liệu — kể cả images / image cấp cao nhất — phải là http://, https:// hoặc data: URI (ví dụ data:image/png;base64,...) và tải được mà không cần đăng nhập. Không hỗ trợ ID tệp mm_file:// của MiniMax. URL mà MiniMax trích lại trong thông báo từ chối được thay bằng [url omitted], nên link có chữ ký không xuất hiện trong thông báo lỗi.
Giới hạn định dạng, kích thước, thời lượng và dung lượng của từng vật liệu do MiniMax quy định; RouteAPI không kiểm tra. Vật liệu không hợp lệ hoặc bị từ chối ngay khi gửi (400, không tính phí), hoặc bị từ chối trong quá trình tạo (tác vụ thành FAILURE và khoản tạm giữ được hoàn).

Ví dụ

Văn bản thành video

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "A paper boat drifting down a rain-soaked street, cinematic lighting",
    "resolution": "768P",
    "ratio": "16:9",
    "duration": 5
  }'

Khung đầu

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "The camera slowly pushes in as the subject looks up and smiles",
    "images": ["https://cdn.example.com/first.jpg"],
    "resolution": "768P",
    "duration": 5
  }'

Khung đầu và khung cuối

Hai phần tử trong images lần lượt thành first_frame và last_frame. ratio bị ép thành adaptive.

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "The scene transitions from morning to sunset while the camera pans smoothly",
    "images": [
      "https://cdn.example.com/first.jpg",
      "https://cdn.example.com/last.jpg"
    ],
    "resolution": "768P",
    "duration": 5
  }'

Ảnh, video và âm thanh tham chiếu

Dùng metadata.content khi cần hơn hai ảnh hoặc cần video / âm thanh tham chiếu. Video tham chiếu có tính phí, nên giữ thời lượng trong khoảng 2–15 giây — xem Tính phí.

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "The character in the image dances to the rhythm of the reference audio, copying the motion of the reference video",
    "resolution": "768P",
    "ratio": "9:16",
    "duration": 8,
    "metadata": {
      "content": [
        { "type": "image_url", "role": "reference_image", "image_url": { "url": "https://cdn.example.com/character.jpg" } },
        { "type": "video_url", "role": "reference_video", "video_url": { "url": "https://cdn.example.com/motion.mp4" } },
        { "type": "audio_url", "role": "reference_audio", "audio_url": { "url": "https://cdn.example.com/music.mp3" } }
      ]
    }
  }'

Mở rộng prompt và watermark của H3-Max

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3-Max",
    "prompt": "A rainy city street at night, neon signs reflected in puddles",
    "resolution": "480P",
    "duration": 6,
    "metadata": {
      "aigc_watermark": false,
      "extra": { "prompt_expansion_mode": "quality" }
    }
  }'

Trạng thái và kết quả tác vụ

Ánh xạ trạng thái

`task.status` của MiniMax	`data.status`	`data.progress`
`queued`	`QUEUED`	`20%`
`running`	`IN_PROGRESS`	`50%`
`succeeded` có `content.url`	`SUCCESS`	`100%`
`succeeded` nhưng không có `content.url`	`FAILURE`	`100%`
`failed`, `cancelled`	`FAILURE`	`100%`
giá trị khác	`IN_PROGRESS`	`30%`

Tác vụ succeeded mà không có URL video bị coi là thất bại với fail_reason là upstream succeeded without video url, và khoản tạm giữ được hoàn. Với failed hoặc cancelled, fail_reason lấy từ task.error.message của MiniMax (mọi URL được thay bằng [url omitted]); khi MiniMax không gửi lý do, giá trị là task failed hoặc task cancelled.

Nếu phản hồi truy vấn là phong bì lỗi ({"type":"error","error":{...}}), vòng truy vấn đó được tính là lỗi và tác vụ được hỏi lại lần sau. Phản hồi hoàn toàn không có đối tượng tác vụ sẽ quay về dạng /v1 cũ, vốn rỗng, nên tác vụ chỉ đơn giản giữ nguyên IN_PROGRESS. Tác vụ không bao giờ đạt trạng thái kết thúc sẽ bị đánh thất bại do hết thời gian chờ của nền tảng — mặc định 24 giờ — với fail_reason là 任务超时（1440分钟）, và khoản tạm giữ được hoàn.

Bản ghi tác vụ

GET /v1/video/generations/{task_id} trả về dòng tác vụ của RouteAPI; mọi trường được mô tả tại Truy vấn tác vụ. Với nhà cung cấp này, các trường hữu ích là:

Trường	Mô tả
`data.status` / `data.progress`	Trạng thái và tiến độ, theo bảng trên
`data.result_url`	URL video sau khi tác vụ thành công
`data.fail_reason`	Lý do thất bại, ngược lại để trống
`data.quota`	Hạn mức đã trừ cho tác vụ
`data.properties.input`	Ảnh chụp yêu cầu RouteAPI gửi lên upstream, URL vật liệu được thay bằng `[omitted, N bytes]`; hữu ích khi khiếu nại khoản trừ
`data.data`	Phản hồi mới nhất của MiniMax

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_FQvcRkHE9wjSWwyISDcrWCKoqCPNdkCx",
    "platform": "35",
    "group": "default",
    "action": "generate",
    "status": "SUCCESS",
    "progress": "100%",
    "fail_reason": "",
    "result_url": "https://cdn.minimax.example/video/424010985738629.mp4?Expires=...",
    "submit_time": 1792412645,
    "start_time": 1792412650,
    "finish_time": 1792412780,
    "data": {
      "task": {
        "id": "424010985738629",
        "status": "succeeded",
        "content": { "url": "https://cdn.minimax.example/video/424010985738629.mp4?Expires=..." },
        "resolution": "768P",
        "usage": {
          "output_seconds": 5,
          "input_seconds": 0,
          "input_image_count": 1
        }
      }
    }
  }
}

Các trường bên trong đáng đọc:

Trường	Mô tả
`data.data.task.id`	ID tác vụ của MiniMax, khác với `task_id` của RouteAPI
`data.data.task.status`	`queued`, `running`, `succeeded`, `failed` hoặc `cancelled`
`data.data.task.content.url`	URL video khi thành công; đây chính là giá trị trong `result_url`
`data.data.task.resolution`	Độ phân giải MiniMax báo cáo. Tính phí theo độ phân giải yêu cầu, không theo giá trị này
`data.data.task.usage.output_seconds`	Số giây video thực tế tạo ra, dùng để quyết toán
`data.data.task.usage.input_seconds`	Số giây video tham chiếu, dùng để quyết toán
`data.data.task.usage.input_image_count`	Số ảnh MiniMax báo cáo; quyết toán dùng số ảnh lúc gửi
`data.data.task.error.code` / `.message`	Chi tiết lỗi khi MiniMax cung cấp

Trước lần truy vấn thành công đầu tiên, data.data là phản hồi gốc lúc gửi ({"task_id": "..."}) và không có trường task. task.usage xuất hiện khi MiniMax trả về, thường là lúc thành công. Luôn rẽ nhánh theo data.status ở lớp ngoài.

Tải video xuống

data.result_url đã trỏ thẳng tới CDN của MiniMax. Liên kết này hết hạn theo lịch của MiniMax, nên hãy tải ngay khi tác vụ báo SUCCESS.

Liên kết CDN trực tiếp: tải mà không kèm header Authorization; một số kho lưu trữ từ chối header xác thực thừa.
https://api.routeapi.ai/v1/videos/{task_id}/content: truyền lại đúng liên kết đã lưu qua RouteAPI và cần Authorization: Bearer $ROUTEAPI_KEY. Nó lấy lại liên kết đã lưu mỗi lần, nên không kéo dài hạn. Dùng khi không muốn lộ host upstream cho client, hoặc khi CDN từ chối truy cập trực tiếp. Trả 404 Task not found với tác vụ không tồn tại và 400 Task is not completed yet, current status: ... trước khi tác vụ thành công.

# direct CDN link
curl -L -o out.mp4 "$RESULT_URL"
# RouteAPI proxy
curl -L -o out.mp4 -H "Authorization: Bearer $ROUTEAPI_KEY" \
  "https://api.routeapi.ai/v1/videos/$TASK_ID/content"

Tính phí

Tính phí theo giây áp dụng khi mô hình có giá cố định được cấu hình cho tài khoản (trang chi tiết mô hình trong console hiển thị giá này). Nếu mô hình chỉ được định giá theo tỷ lệ, áp dụng khoản trừ theo tác vụ thông thường và không có quyết toán khi hoàn tất. Với tính phí theo giây, chi phí gồm ba thành phần:

Thành phần	Đơn giá	Tính khi gửi (tạm giữ)	Tính khi quyết toán
Video đầu ra	mỗi giây, theo độ phân giải yêu cầu	`duration` yêu cầu	`min(usage.output_seconds, duration)`
Video tham chiếu đầu vào	mỗi giây, theo độ phân giải yêu cầu	15 giây khi `content` có `reference_video`	`usage.input_seconds`, chỉ hợp lệ trong khoảng 2–15 giây
Ảnh	mỗi ảnh vượt số miễn phí	toàn bộ mục ảnh trong `content` đã dựng, kể cả khung đầu/cuối	đúng số ảnh trong ảnh chụp lúc gửi

Giá và số ảnh miễn phí được cấu hình theo tài khoản; giá trị tích hợp cho 5 ảnh miễn phí với MiniMax-H3 và 2 với MiniMax-H3-Max, nhưng console là căn cứ. Trang này không nêu bất kỳ mức giá nào.

Thời điểm	Số giây đầu ra	Số giây video tham chiếu
Tạm giữ khi gửi	`duration` yêu cầu	15 giây nếu yêu cầu có video tham chiếu
Quyết toán khi thành công	`usage.output_seconds`, không vượt quá `duration` yêu cầu	`usage.input_seconds` khi nằm trong 2–15 giây

Quy tắc:

Quyết toán chỉ hoàn lại: khoản trừ cuối cùng là giá trị nhỏ hơn giữa số tính lại và khoản tạm giữ.
Quyết toán dùng đơn giá đã chốt lúc gửi. Đổi giá trong lúc tác vụ chạy không ảnh hưởng.
Không có video tham chiếu thì hoàn toàn không có thành phần số giây đầu vào, và usage.input_seconds bị bỏ qua.
Âm thanh tham chiếu miễn phí, thành phần ảnh không đổi khi quyết toán.
Vì yêu cầu có video tham chiếu tạm giữ 15 giây đầu vào, số dư phải đủ cho trường hợp xấu nhất này dù video ngắn hơn.
Nếu thiếu usage, output_seconds bằng 0 hoặc lớn hơn 15, hoặc (khi có video tham chiếu) input_seconds thiếu hay ngoài 2–15, RouteAPI giữ toàn bộ khoản tạm giữ và không hoàn. Giữ video tham chiếu trong 2–15 giây để tránh điều này.
Tác vụ thất bại hoặc hết thời gian chờ hoàn toàn bộ khoản tạm giữ; yêu cầu bị từ chối với 400 không bị tính phí.
Khi tính phí theo giây, header X-New-Api-Other-Ratios trong phản hồi gửi mang hệ số nhân áp lên đơn giá mô hình dưới khóa h3_units (tác vụ 5 giây 768P là {"h3_units": 5}). Với dòng 2.3 và mô hình H3 không có giá cố định, header là {}.

Ví dụ tính toán

Giá dưới đây chỉ là giả định để minh hoạ phép tính: MiniMax-H3 ở 768P giá $0.10 mỗi giây đầu ra, $0.10 mỗi giây video tham chiếu, và $0.04 mỗi ảnh vượt 5 ảnh miễn phí. Yêu cầu 10 giây với hai ảnh tham chiếu và một video tham chiếu:

Tạm giữ: 10 × 0.10 (đầu ra) + 15 × 0.10 (video tham chiếu, theo mức trần) + max(0, 2 − 5) × 0.04 (ảnh) = $2.50.
MiniMax trả output_seconds: 8 và input_seconds: 6: 8 × 0.10 + 6 × 0.10 + 0 = $1.40.
Chênh lệch $1.10 được hoàn về số dư.

Lỗi

Yêu cầu được kiểm tra đầy đủ trước khi tạm giữ, nên 400 không mất phí. Các từ chối nghiệp vụ của MiniMax nằm trong phản hồi HTTP 200 và được ánh xạ như sau:

`base_resp.status_code` của MiniMax	Ý nghĩa	HTTP trả về	`code`
`1026`	Từ chối nội dung / an toàn	`400`	`1026`
`2013`	Lỗi tham số	`400`	`2013`
`1002`	Bị giới hạn tần suất	`429`	`1002`
`1004`, `2049`	Lỗi khóa / xác thực upstream	`401`, thường trả về `503`	`1004` / `2049`, hoặc `get_channel_failed`
`1008`	Cạn số dư upstream	`503`	`get_channel_failed`
mã khác	Lỗi nghiệp vụ không rõ	`502`	mã số
— (body không đọc được, hoặc phong bì `type: "error"`)	Phản hồi gửi sai định dạng	`502`	`invalid_response`
— (`task_id` rỗng)	Upstream không trả ID tác vụ	`502`	`upstream_task_id_missing`

Lỗi tài khoản upstream không bao giờ được trả nguyên văn. Bộ chuyển đổi ánh xạ 1008 thành 402, 1004 / 2049 thành 401; sau đó RouteAPI phân loại lỗi là lỗi kênh và trả 503 get_channel_failed kèm câu chung “dịch vụ upstream tạm thời không khả dụng”, sau khi thử kênh khác nếu có. 402 từ 1008 cũng được trả thành 503 vì lý do tương tự. Trong các trường hợp này, status_msg của MiniMax không tới được bạn. 429 giữ nguyên mã trạng thái nhưng thông báo được thay bằng nhắc thử lại chung. 400 mang văn bản gốc của MiniMax với tiền tố hailuo api error: .

Nếu MiniMax trả mã HTTP khác 200, body không được phân tích: bạn nhận mã fail_to_fetch_task cùng mã trạng thái đó. Truy vấn task_id không tồn tại hoặc thuộc tài khoản khác trả 400 với mã task_not_exist.

Lỗi phát sinh trước khi yêu cầu tới MiniMax tuân theo quy tắc chung trong Lỗi thường gặp: 401 khi thiếu hoặc sai API Key, 403 insufficient_user_quota khi số dư không đủ cho khoản tạm giữ (kể cả trường hợp xấu nhất 15 giây video tham chiếu), và 403 kèm This token has no access to model ... khi khóa không được phép dùng mô hình.

Các thông báo 400 thường gặp (mã invalid_request trừ khi có ghi chú):

`message`	Nguyên nhân
`prompt is required`	Thiếu `prompt` hoặc `prompt` rỗng
`seconds must be between 1 and 3600` (mã `invalid_seconds`)	`duration` cấp cao nhất âm hoặc lớn hơn 3600
`invalid seconds: abc`	`seconds` không phải chuỗi số nguyên
`<model> 请使用 resolution(480P/768P/2K),不支持 size`	Đã gửi `size` ở cấp cao nhất hoặc trong `metadata`; thông báo nêu mô hình bạn yêu cầu và luôn liệt kê 480P/768P/2K
`invalid resolution: 1080P, MiniMax-H3 supports 768P, 2K`	Độ phân giải không được mô hình đó hỗ trợ
`invalid duration: 3, MiniMax-H3 supports integer 4-15`	Thời lượng dưới mức tối thiểu, trên 15, hoặc không nguyên
`invalid ratio: 2:1, supports adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16`	Tỷ lệ không có trong danh sách
`text-to-video does not support ratio adaptive`	`adaptive` trên yêu cầu không có khung và không có tham chiếu
`at most 2 top-level images (first_frame, last_frame), got 3; use metadata.content for reference media`	`images` có hơn 2 phần tử
`images must not contain empty values`	Có phần tử rỗng trong `images`
`metadata.content cannot be combined with top-level images`	Gửi cả hai
`metadata.content must be a non-empty array`	`content` là `[]`
`prompt 与 metadata.content 中的 text 冲突`	Mục `text` khác với `prompt`
`metadata.content accepts at most one text item`	Nhiều hơn một mục `text`
`text exceeds 7000 characters`	Prompt dài hơn 7000 ký tự
`invalid content type "foo"`	`type` không rõ
`invalid role "foo" for image_url`	`role` của ảnh không rõ
`image_url without role is only allowed as the single input image`	Ảnh không có `role` dùng chung với vật liệu khác
`last_frame requires first_frame`	Chỉ gửi khung cuối
`at most one first_frame and one last_frame`	Trùng role khung
`first/last frame images cannot be combined with reference media`	Trộn khung với vật liệu tham chiếu
`at most 9 reference images` / `at most 3 reference videos` / `at most 3 reference audios` / `at most 12 media items`	Vượt giới hạn theo loại hoặc tổng số vật liệu
`video_url requires role reference_video` / `audio_url requires role reference_audio`	Sai hoặc thiếu `role` cho loại mục đó
`image_url.url must be an http(s) URL or data URI` (tương tự `video_url` / `audio_url`)	Scheme URL không hỗ trợ, kể cả `mm_file://`
`MiniMax-H3 does not support extra`	Gửi `metadata.extra` cho mô hình không phải Max
`invalid extra.prompt_expansion_mode: balance, supports disabled, balanced, quality`	Chế độ mở rộng không rõ
`invalid metadata: ...`	Khóa `metadata` sai kiểu JSON

Lỗi sau khi gửi thành công — kiểm duyệt nội dung, vật liệu không tải được, tác vụ bị huỷ hoặc hết thời gian chờ — không bao giờ hiện dưới dạng lỗi HTTP. Chúng hiện trên bản ghi tác vụ là FAILURE kèm fail_reason, và khoản tạm giữ được hoàn.

Khác biệt so với API MiniMax

Đường dẫn là của RouteAPI: POST /v1/video/generations và GET /v1/video/generations/{task_id}. Các endpoint /v2/video_generation và /v2/query/video_generation/{id} của MiniMax không được mở ra, nên chỉ đổi Base URL trong SDK chính thức sẽ không dùng được.
Prompt nằm ở prompt cấp cao nhất, còn mảng content của MiniMax nằm ở metadata.content. RouteAPI dựng content cho upstream, gồm cả mục text, và cách viết tắt khung đầu / khung cuối qua images không có tương đương bên MiniMax.
task_id bạn nhận là của RouteAPI. ID tác vụ của MiniMax chỉ xuất hiện ở data.data.task.id.
RouteAPI kiểm tra kiểu mục, role, số lượng và scheme URL trước khi chuyển tiếp — chặt hơn MiniMax, vốn để phần lớn cho bước tạo.
Chỉ model, content, resolution, duration, ratio, aigc_watermark và extra được chuyển tiếp. Các tham số MiniMax khác, kể cả callback_url, bị bỏ.
Vật liệu phải là URL http(s) công khai hoặc data:; không dùng được ID tệp mm_file:// của MiniMax.
Khi bỏ trống resolution và duration, RouteAPI điền 768P, 5 giây, nên upstream luôn nhận giá trị tường minh.
Khi thành công, RouteAPI lưu thẳng content.url của MiniMax làm result_url; không cần gọi bước lấy tệp riêng.

Script truy vấn hoàn chỉnh

Cần bash, curl và jq. Script gửi tác vụ văn bản thành video 5 giây, truy vấn mỗi 15 giây tối đa 30 phút, tải kết quả (chỉ thêm Authorization cho dạng proxy RouteAPI) và in usage phục vụ tính phí.

#!/usr/bin/env bash
set -euo pipefail

: "${ROUTEAPI_KEY:?export ROUTEAPI_KEY first}"
BASE="${ROUTEAPI_BASE:-https://api.routeapi.ai}"
AUTH="Authorization: Bearer $ROUTEAPI_KEY"

TASK_ID=$(curl -sS -X POST "$BASE/v1/video/generations" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "A paper boat drifting down a rain-soaked street, cinematic lighting",
    "resolution": "768P",
    "ratio": "16:9",
    "duration": 5
  }' | jq -er '.task_id')

echo "task: $TASK_ID"

for _ in $(seq 1 120); do
  RESP=$(curl -sS "$BASE/v1/video/generations/$TASK_ID" -H "$AUTH")
  STATUS=$(jq -r '.data.status // empty' <<<"$RESP")
  echo "status: ${STATUS:-unknown} $(jq -r '.data.progress // ""' <<<"$RESP")"

  case "$STATUS" in
    SUCCESS)
      URL=$(jq -r '.data.result_url' <<<"$RESP")
      OUT="$TASK_ID.mp4"
      if [[ "$URL" == *"/v1/videos/"*"/content" ]]; then
        curl -sSL -o "$OUT" -H "$AUTH" "$URL"
      else
        curl -sSL -o "$OUT" "$URL"
      fi
      echo "saved: $OUT"
      jq -r '.data.data.task.usage // {}' <<<"$RESP"
      exit 0
      ;;
    FAILURE)
      echo "failed: $(jq -r '.data.fail_reason' <<<"$RESP")" >&2
      exit 1
      ;;
  esac

  sleep 15
done

echo "gave up after 30 minutes" >&2
exit 1

MiniMax-Hailuo-2.3

MiniMax-Hailuo-2.3 và MiniMax-Hailuo-2.3-Fast dùng API /v1/video_generation của MiniMax và tính phí theo tác vụ, không theo giây. RouteAPI gửi yêu cầu, truy vấn /v1/query/video_generation, rồi lấy kết quả qua /v1/files/retrieve của MiniMax và lưu URL tải xuống vào result_url.

ID mô hình	Ghi chú
`MiniMax-Hailuo-2.3`	Văn bản thành video và ảnh thành video
`MiniMax-Hailuo-2.3-Fast`	Bản nhanh và rẻ hơn của 2.3

Cả hai mặc định 768P và 6 giây. API tác vụ không kiểm tra phạm vi độ phân giải hay thời lượng của dòng này ngoài giới hạn chung 0–3600: giá trị được chuyển nguyên trạng và MiniMax quyết định. Playground trong console cung cấp 768P / 1080P và 6 hoặc 10 giây, trong đó 1080P chỉ cho phép 6 giây.

Cách ánh xạ yêu cầu (2.3)

Trường của khung chung	Bộ chuyển đổi làm gì
`prompt`	Gửi thành `prompt`; `metadata.prompt` ghi đè nếu có
`duration`	Gửi thành `duration`; thiếu hoặc `0` thì thành `6`
`size`	Đổi thành `resolution` theo chuỗi con: `1080` → `1080P`, `768` → `768P`, `720` → `720P`, `512` → `512P`; giá trị khác về mặc định của mô hình
`images` / `image`	Không đọc. Ảnh đầu vào phải đi qua `metadata.first_frame_image`
`ratio`, `generate_audio`, `seconds`	Không đọc. Dòng này không có tham số tỷ lệ khung hình hay nhạc nền
`metadata`	Giải mã thành các trường của MiniMax theo đúng tên trường của MiniMax

Dòng này không đọc resolution ở cấp cao nhất: hãy dùng size hoặc metadata.resolution.

Tham số nhà cung cấp (2.3)

Tất cả nằm dưới metadata. Sai kiểu JSON (ví dụ "duration": "abc") khiến chuyển đổi thất bại với 500 build_request_failed, không phải 400; khóa lạ bị bỏ qua.

Trường	Kiểu	Mô tả
`resolution`	string	`768P` hoặc `1080P`; ghi đè giá trị do `size` tạo ra
`duration`	integer	6 hoặc 10 giây; ghi đè `duration` cấp cao nhất
`first_frame_image`	string	Ảnh khung đầu (URL công khai hoặc `data:` URI base64), chuyển nguyên trạng
`last_frame_image`	string	Khung cuối cho chế độ đầu-cuối, chuyển nguyên trạng
`subject_reference`	array	Tham chiếu chủ thể: `[{"type": "character", "image": ["<url>"]}]`
`prompt_optimizer`	boolean	Để MiniMax viết lại prompt; `false` tường minh vẫn được chuyển
`fast_pretreatment`	boolean	Cờ tiền xử lý nhanh của MiniMax, chuyển nguyên trạng
`aigc_watermark`	boolean	Thêm watermark AIGC của nhà cung cấp
`callback_url`	string	Chuyển cho MiniMax. RouteAPI không đăng ký và không nhận callback — hãy truy vấn kết quả
`prompt`	string	Ghi đè `prompt` cấp cao nhất

metadata.model bị ghi đè bằng tên mô hình upstream của kênh, nên không thể chuyển sang mô hình khác (ví dụ đắt hơn) qua metadata.

Ảnh thành video (2.3)

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Hailuo-2.3",
    "prompt": "The camera slowly pushes in as the subject looks up and smiles",
    "duration": 6,
    "metadata": {
      "resolution": "1080P",
      "first_frame_image": "https://cdn.example.com/first.jpg"
    }
  }'

Ánh xạ trạng thái (2.3)

MiniMax v1 trả Preparing, Queueing, Processing, Success và Fail.

Trạng thái upstream	Trạng thái bản ghi	Tiến độ
`Preparing`, `Queueing`	`IN_PROGRESS`	`30%`
`Processing`	`IN_PROGRESS`	`50%`
`Success`	`SUCCESS`	`100%`
`Fail`	`FAILURE`	`100%`

Khi thành công, bộ chuyển đổi gọi endpoint lấy tệp của MiniMax với file_id trả về và lưu URL tải xuống vào result_url. URL này hết hạn theo lịch của MiniMax; GET /v1/videos/{task_id}/content truyền URL đã lưu qua RouteAPI và cần Authorization.

Tính phí (2.3)

Dòng 2.3 tính theo đơn giá tác vụ cấu hình trong console. Độ phân giải và thời lượng bạn gửi không làm đổi khoản trừ, và không có quyết toán chênh lệch khi hoàn tất; tác vụ thất bại hoàn lại khoản tạm giữ. X-New-Api-Other-Ratios là {}.

Lỗi (2.3)

Trạng thái	`code`	Ý nghĩa
400	`invalid_request`	Thiếu hoặc rỗng `prompt`, hoặc JSON sai định dạng
400	`invalid_seconds`	`duration` / `seconds` âm hoặc lớn hơn 3600
400	Mã số của MiniMax	MiniMax từ chối tác vụ; thông báo là `status_msg` của nó
400	`task_not_exist`	`task_id` không rõ hoặc thuộc tài khoản khác
500	`build_request_failed`, `do_request_failed`	Chuyển đổi metadata thất bại, hoặc không tới được upstream
500	`unmarshal_response_body_failed`	MiniMax trả về dạng mà bộ chuyển đổi không nhận ra
502	`upstream_task_id_missing`	Phản hồi gửi không có ID tác vụ
mã upstream	`fail_to_fetch_task`	MiniMax trả mã HTTP khác 200

Với dòng này, mọi từ chối nghiệp vụ của MiniMax đều trả 400, kể cả giới hạn tần suất; mã số và status_msg được chuyển nguyên, nên hãy xem mã số thay vì mã HTTP. Ngoại lệ là lỗi thiếu số dư upstream: khi status_msg của MiniMax khớp từ khóa tính phí tích hợp của RouteAPI (thiếu số dư và tương tự), phản hồi được làm sạch thành 503 get_channel_failed với thông báo chung, và lỗi được ghi nhận là lỗi kênh (kênh chỉ tự động bị vô hiệu hoá khi tính năng tự động vô hiệu hoá được bật và kênh cho phép).

Lỗi sau khi gửi (kiểm duyệt, quá thời gian phía nhà cung cấp) hiện trên bản ghi tác vụ là FAILURE kèm fail_reason, và khoản đã tạm giữ được hoàn.