MiniMax Hailuo

Hailuo 是 MiniMax 的视频生成系列。同一个渠道提供两代接口：MiniMax-H3 和 MiniMax-H3-Max 使用 MiniMax 的 /v2 接口，请求体是 content 数组，按秒结算；MiniMax-Hailuo-2.3 系列使用较旧的 /v1 接口，按任务固定价计费（见本页最后一部分）。

任务通过通用视频端点提交、轮询和下载，见创建任务和查询任务。本页说明这个厂商的适配器读取哪些字段、请求如何组装，以及如何计费。

模型

模型 ID	分辨率	时长（整数秒）	默认值	提示词扩写
`MiniMax-H3`	`768P`、`2K`	4–15	`768P`、5 秒	不支持
`MiniMax-H3-Max`	`480P`、`768P`	5–15	`768P`、5 秒	支持

模型 ID 区分大小写，请按上表原样填写。账户只能用被路由到它的模型，单价也因账户而异；GET /v1/models 是当前 Key 的权威列表。
只有 MiniMax-H3-Max 接受 extra。给 MiniMax-H3 传 extra 会返回 400。
两个模型都支持文生视频、首帧、首尾帧，以及参考图 / 参考视频 / 参考音频。

请求参数

字段	类型	必填	默认值	说明
`model`	string	是	—	模型 ID，取自 `GET /v1/models`
`prompt`	string	是	—	提示词，去掉空白后为空会被拒绝，最长 7000 个字符
`resolution`	string	否	`768P`	不区分大小写，必须是该模型支持的档位
`duration`	integer	否	`5`	整数秒，必须在模型范围内
`seconds`	string	否	—	时长的字符串写法，只在没有 `duration`（或为 `0`）时生效
`ratio`	string	否	见下文	画面比例
`images`	string[]	否	—	1 张作为首帧，2 张依次作为首帧和尾帧，最多 2 张
`image`	string	否	—	单张图片，仅在 `images` 为空时使用
`metadata`	object	否	—	MiniMax 参数，见下一节

优先级规则：

metadata.resolution、metadata.duration、metadata.ratio 会覆盖同名的顶层字段。
seconds 只在顶层 duration 缺失或为 0 时读取，而 metadata.duration 的优先级高于两者。
metadata.duration 按数字解析，所以 5.5 会报 invalid duration。与顶层 duration 不同，这里写 0 不算“未设置”，而是越界。想保留默认值就不要写这个键。
不支持 size。顶层 size 或 metadata.size 会返回 MiniMax-H3 请使用 resolution(480P/768P/2K),不支持 size，请改用 resolution。
除 size 外，本厂商不读取的顶层字段（例如 generate_audio、input_reference）会被忽略，不会报错。

metadata 参数

字段	类型	说明
`content`	array	输入素材，见 content 素材与限制。不能与顶层 `images` / `image` 同传
`resolution`	string	覆盖顶层 `resolution`
`duration`	number	覆盖顶层 `duration` 和 `seconds`，必须是范围内的整数
`ratio`	string	覆盖顶层 `ratio`
`aigc_watermark`	boolean 或 string	`true` / `false`。也接受字符串 `"true"` / `"false"`，multipart 表单提交的就是字符串。不传时由上游决定
`extra.prompt_expansion_mode`	string	`disabled`、`balanced`、`quality`，仅 `MiniMax-H3-Max` 支持
`size`	—	返回 `400`

metadata 会解码进强类型结构：上表字段的 JSON 类型写错（例如 "duration": "abc"，或把 content 写成对象）会返回 400，错误信息以 invalid metadata: 开头，不扣费。不在表里的键（seed、callback_url 等）会被忽略，不会发给 MiniMax；RouteAPI 不发送回调，请轮询结果。

画面比例 ratio

可选值：adaptive、21:9、16:9、4:3、1:1、3:4、9:16，不区分大小写。

请求类型	不传 `ratio` 时	规则
纯文生视频（无首尾帧、无参考素材）	`16:9`	传 `adaptive` 会报 `text-to-video does not support ratio adaptive`
首帧，或首尾帧	`adaptive`	强制为 `adaptive`，你传的值会被忽略，也不会被校验
参考素材（参考图 / 视频 / 音频）	`adaptive`	七个值都可以用

content 素材与限制

metadata.content 是有序数组。每个条目有一个 type、一个与之对应的载荷字段，以及可选的 role：

`type`	载荷	可用 `role`	数量上限
`text`	`text`	无	1 条，且必须与 `prompt` 一致
`image_url`	`image_url.url`	`first_frame`	1
`image_url`	`image_url.url`	`last_frame`	1，且必须同时有 `first_frame`
`image_url`	`image_url.url`	`reference_image`	9
`image_url`	`image_url.url`	无	仅当它是唯一素材时可用
`video_url`	`video_url.url`	`reference_video`（必填）	3
`audio_url`	`audio_url.url`	`reference_audio`（必填）	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://..." } }

请求发出前会校验以下规则：

一次请求的素材总数不超过 12 个，其中参考图最多 9 张、参考视频最多 3 段、参考音频最多 3 段。
首帧 / 尾帧与参考素材不能混用。reference_image、reference_video、reference_audio 之间可以自由组合。
不带 role 的 image_url 只允许作为唯一的素材出现，此时按首帧处理。
content 里没有 text 条目时，RouteAPI 会用顶层 prompt 自动补一条；如果有，最多一条，且内容必须等于去掉首尾空白后的 prompt，否则返回 prompt 与 metadata.content 中的 text 冲突。
content 与顶层 images / image 互斥。
每个条目只转发与其 type 对应的字段，多余的键会被丢弃。
素材 URL（包括顶层 images / image）只接受 http://、https:// 或 data: URI（如 data:image/png;base64,...），必须无需登录即可下载。不支持 MiniMax 的 mm_file:// 文件 ID。MiniMax 在拒绝信息里回显的 URL 会被替换为 [url omitted]，带签名的素材地址不会出现在错误信息中。
单个素材的格式、尺寸、时长和大小限制以 MiniMax 为准，RouteAPI 不做校验。不符合要求的素材可能在提交时被拒绝（400，不扣费），也可能在生成过程中被拒绝（任务判为 FAILURE，预扣额度退回）。

示例

文生视频

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
  }'

首帧

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
  }'

首尾帧

images 里的两项依次作为 first_frame 和 last_frame。ratio 会被强制为 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
  }'

参考图 + 参考视频 + 参考音频

需要超过 2 张图片，或需要参考视频 / 参考音频时，用 metadata.content。参考视频会计费，请把时长控制在 2–15 秒之间——见计费。

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" } }
      ]
    }
  }'

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" }
    }
  }'

任务状态和结果

状态映射

MiniMax `task.status`	`data.status`	`data.progress`
`queued`	`QUEUED`	`20%`
`running`	`IN_PROGRESS`	`50%`
`succeeded` 且带 `content.url`	`SUCCESS`	`100%`
`succeeded` 但没有 `content.url`	`FAILURE`	`100%`
`failed`、`cancelled`	`FAILURE`	`100%`
其它值	`IN_PROGRESS`	`30%`

succeeded 但没有视频地址时，任务判为失败，fail_reason 为 upstream succeeded without video url，预扣额度退回。failed 或 cancelled 时，fail_reason 取 MiniMax 的 task.error.message（其中的 URL 会被替换为 [url omitted]）；MiniMax 没有给原因时分别是 task failed 和 task cancelled。

查询返回错误信封（{"type":"error","error":{...}}）时，这一轮轮询记为失败，下一轮继续查询。返回体里完全没有任务对象时，会回退到旧的 /v1 结构解析，结果为空，任务只是保持 IN_PROGRESS。一直无法进入终态的任务会由平台超时判失败——默认 24 小时——fail_reason 为 任务超时（1440分钟），预扣额度退回。

任务记录

GET /v1/video/generations/{task_id} 返回 RouteAPI 的任务行，所有字段见查询任务。本厂商常用的字段：

字段	说明
`data.status` / `data.progress`	任务状态和进度，取自上表
`data.result_url`	任务成功后的视频地址
`data.fail_reason`	失败原因，成功时为空
`data.quota`	该任务扣除的额度
`data.properties.input`	RouteAPI 发给上游的请求快照，素材 URL 被替换为 `[omitted, N bytes]`，对账时有用
`data.data`	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
        }
      }
    }
  }
}

值得读取的内层字段：

字段	说明
`data.data.task.id`	MiniMax 的任务 ID，与 RouteAPI 的 `task_id` 不同
`data.data.task.status`	`queued`、`running`、`succeeded`、`failed` 或 `cancelled`
`data.data.task.content.url`	成功时的视频地址，`result_url` 保存的就是它
`data.data.task.resolution`	MiniMax 上报的分辨率。计费按请求的分辨率，不按这个
`data.data.task.usage.output_seconds`	实际输出视频的秒数，用于结算
`data.data.task.usage.input_seconds`	输入参考视频的秒数，用于结算
`data.data.task.usage.input_image_count`	MiniMax 上报的图片张数；结算按提交时的张数
`data.data.task.error.code` / `.message`	MiniMax 给出失败原因时的错误码和信息

第一次成功轮询之前，data.data 是提交时的原始返回（{"task_id": "..."}），没有 task 字段。task.usage 只在 MiniMax 返回时出现，通常是在任务成功时。判断任务是否结束请始终看外层 data.status。

下载视频

data.result_url 直接指向 MiniMax 的 CDN。该地址会按 MiniMax 的策略过期，任务变成 SUCCESS 后请尽快下载。

CDN 直链：不要带 Authorization 请求头，部分存储会拒绝多余的鉴权头。
https://api.routeapi.ai/v1/videos/{task_id}/content：把同一个已保存的地址经 RouteAPI 转发，必须带 Authorization: Bearer $ROUTEAPI_KEY。它每次重新拉取已保存的地址，所以不会延长有效期。适合不想让客户端看到上游域名、或 CDN 拒绝直接访问的场景。任务不存在时返回 404 Task not found，任务成功前返回 400 Task is not completed yet, current status: ...。

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

计费

账户为该模型配置了固定价（控制台模型详情页会显示）时，H3 按秒计费。如果模型只配了模型倍率，则按常规的按任务预扣，完成后不做差额结算。按秒计费时，一个任务的费用由三项相加：

计费项	单价	提交时预扣	结算时
输出视频	按请求分辨率，每秒单价	请求的 `duration`	`min(usage.output_seconds, duration)`
参考视频输入	按请求分辨率，每秒单价	`content` 里有 `reference_video` 时按 15 秒	`usage.input_seconds`，仅在 2–15 秒内有效
图片	超出免费张数后按张计价	组装后 `content` 中的全部图片，含首尾帧	按提交快照的同一张数

价格和免费图片张数按账户配置；内置默认值是 MiniMax-H3 免费 5 张、MiniMax-H3-Max 免费 2 张，但以控制台为准。本页不列出任何价格。

时机	输出秒数	参考视频秒数
提交时预扣	请求的 `duration`	有参考视频时按 15 秒
成功后结算	`usage.output_seconds`，不超过请求的 `duration`	`usage.input_seconds`，须在 2–15 秒之间

规则：

结算只退不补：最终扣费取重算金额与预扣额度中的较小值。
结算使用提交时冻结的单价，任务进行中调价不影响已提交的任务。
没有参考视频时完全没有输入秒数这一项，usage.input_seconds 会被忽略。
参考音频不单独收费，图片这一项在结算时不变。
因为有参考视频时会预扣 15 秒输入，账户余额必须能覆盖这个最坏情况，即使视频本身更短。
上游没有返回 usage、output_seconds 为 0 或超过 15 秒，或有参考视频时 input_seconds 缺失 / 不在 2–15 秒之间，RouteAPI 会保留全部预扣额度，不退款。把参考视频控制在 2–15 秒可以避免这种情况。
失败或超时的任务退回全部预扣额度；参数校验失败（400）不扣费。
按秒计费时，提交响应的 X-New-Api-Other-Ratios 头会带上作用于模型单价的倍率，键为 h3_units（5 秒 768P 任务为 {"h3_units": 5}）。2.3 系列、以及未配固定价的 H3 模型该头为 {}。

计算示例

以下价格仅用于演示算术：假设 MiniMax-H3 768P 输出每秒 $0.10、参考视频每秒 $0.10、超出免费 5 张后每张 $0.04。请求 10 秒，带 2 张参考图和 1 段参考视频：

预扣：10 × 0.10（输出）+ 15 × 0.10（参考视频按下限预扣）+ max(0, 2 − 5) × 0.04（图片）= $2.50。
MiniMax 返回 output_seconds: 8、input_seconds: 6：8 × 0.10 + 6 × 0.10 + 0 = $1.40。
差额 $1.10 退回余额。

错误

提交前会先做完整校验，所以 400 不扣费。MiniMax 的业务拒绝会包在 HTTP 200 响应里返回，映射如下：

MiniMax `base_resp.status_code`	含义	返回给你的状态码	`code`
`1026`	内容 / 安全审核拒绝	`400`	`1026`
`2013`	参数错误	`400`	`2013`
`1002`	触发限流	`429`	`1002`
`1004`、`2049`	上游 Key / 鉴权失败	`401`，通常返回 `503`	`1004` / `2049`，或 `get_channel_failed`
`1008`	上游账户余额不足	`503`	`get_channel_failed`
其它业务码	未知业务错误	`502`	数字错误码
—（返回体无法解析，或 `type: "error"` 信封）	提交响应格式异常	`502`	`invalid_response`
—（`task_id` 为空）	上游没有返回任务 ID	`502`	`upstream_task_id_missing`

上游账户类失败不会原样透出：适配器把 1008 映射为 402、把 1004 / 2049 映射为 401，随后 RouteAPI 会把它判定为渠道故障，返回 503 get_channel_failed 和通用的“上游服务暂时不可用”文案，有其他渠道时先换渠道重试。1008 的 402 同样按此处理成 503。这些情况下 MiniMax 的 status_msg 不会传给你。429 保留状态码，但文案会替换成通用的稍后重试提示。400 会带上 MiniMax 的原始文案，前缀为 hailuo api error: 。

MiniMax 返回非 200 的 HTTP 状态码时，响应体不会被解析：你会拿到该状态码和错误码 fail_to_fetch_task。查询不存在或属于其他账户的 task_id 返回 400，错误码 task_not_exist。

在请求到达 MiniMax 之前产生的错误遵循常见错误里的通用规则：缺少或无效的 API Key 返回 401；余额不足以覆盖预扣（包括参考视频 15 秒的最坏情况）返回 403 insufficient_user_quota；Key 无权使用该模型返回 403 和 This token has no access to model ...。

常见 400 提示（除特别说明外错误码为 invalid_request）：

`message`	原因
`prompt is required`	`prompt` 缺失或为空
`seconds must be between 1 and 3600`（错误码 `invalid_seconds`）	顶层 `duration` 为负或大于 3600
`invalid seconds: abc`	`seconds` 不是整数字符串
`<model> 请使用 resolution(480P/768P/2K),不支持 size`	顶层或 `metadata` 里传了 `size`；文案里的模型名是你请求的模型，括号内的档位固定列出 480P/768P/2K
`invalid resolution: 1080P, MiniMax-H3 supports 768P, 2K`	分辨率不在该模型支持范围内
`invalid duration: 3, MiniMax-H3 supports integer 4-15`	时长低于模型下限、超过 15 秒，或不是整数
`invalid ratio: 2:1, supports adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16`	比例不在支持列表内
`text-to-video does not support ratio adaptive`	无首尾帧、无参考素材时传了 `adaptive`
`at most 2 top-level images (first_frame, last_frame), got 3; use metadata.content for reference media`	`images` 超过 2 张
`images must not contain empty values`	`images` 里有空字符串
`metadata.content cannot be combined with top-level images`	两者同时传了
`metadata.content must be a non-empty array`	`content` 是 `[]`
`prompt 与 metadata.content 中的 text 冲突`	`text` 条目与 `prompt` 不一致
`metadata.content accepts at most one text item`	`text` 条目多于一条
`text exceeds 7000 characters`	提示词超过 7000 个字符
`invalid content type "foo"`	`type` 不在支持列表内
`invalid role "foo" for image_url`	图片的 `role` 不在支持列表内
`image_url without role is only allowed as the single input image`	不带 `role` 的图片与其它素材同传
`last_frame requires first_frame`	只传了尾帧
`at most one first_frame and one last_frame`	首帧或尾帧重复
`first/last frame images cannot be combined with reference media`	首尾帧与参考素材混用
`at most 9 reference images` / `at most 3 reference videos` / `at most 3 reference audios` / `at most 12 media items`	某一类或总素材数超限
`video_url requires role reference_video` / `audio_url requires role reference_audio`	该类型条目的 `role` 写错或没写
`image_url.url must be an http(s) URL or data URI`（`video_url` / `audio_url` 同理）	素材 URL 协议不支持，包括 `mm_file://`
`MiniMax-H3 does not support extra`	给非 Max 模型传了 `metadata.extra`
`invalid extra.prompt_expansion_mode: balance, supports disabled, balanced, quality`	扩写模式不在支持列表内
`invalid metadata: ...`	`metadata` 字段的 JSON 类型不对

提交成功之后发生的失败——内容审核、素材无法下载、任务被取消或超时——不会以 HTTP 错误返回。它们会以 FAILURE 连同 fail_reason 出现在任务记录中，预扣额度退回。

与 MiniMax 官方接口的区别

路径是 RouteAPI 的：POST /v1/video/generations 和 GET /v1/video/generations/{task_id}。不提供 MiniMax 的 /v2/video_generation 和 /v2/query/video_generation/{id}，所以官方 SDK 只改 Base URL 无法接入。
提示词写在顶层 prompt，MiniMax 的 content 数组写在 metadata.content。上游的 content（含 text 条目）由 RouteAPI 组装；用顶层 images 传首帧 / 首尾帧的写法 MiniMax 没有。
你拿到的 task_id 是 RouteAPI 的。MiniMax 自己的任务 ID 只出现在 data.data.task.id。
RouteAPI 会在转发前校验条目类型、role、数量和 URL 协议，比 MiniMax 更严格，后者大多留到生成阶段再判断。
只会转发 model、content、resolution、duration、ratio、aigc_watermark 和 extra。其它 MiniMax 参数（包括 callback_url）一律丢弃。
素材必须是公网 http(s) 或 data: URL，不能使用 MiniMax 的 mm_file:// 文件 ID。
省略 resolution 和 duration 时 RouteAPI 会补成 768P、5 秒，所以上游总是收到明确的值。
成功时 RouteAPI 直接把 MiniMax 的 content.url 存为 result_url，不需要再调用单独的文件查询接口。

完整轮询脚本

需要 bash、curl 和 jq。脚本提交一个 5 秒的文生视频任务，每 15 秒查询一次、最多 30 分钟，然后下载结果（只有 RouteAPI 代理地址才带 Authorization），并打印计费相关的 usage。

#!/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 和 MiniMax-Hailuo-2.3-Fast 使用 MiniMax 的 /v1/video_generation 接口，按任务计价而不是按秒。RouteAPI 提交后轮询 /v1/query/video_generation，再通过 MiniMax 的 /v1/files/retrieve 换取下载地址，存进 result_url。

模型 ID	说明
`MiniMax-Hailuo-2.3`	文生视频与图生视频
`MiniMax-Hailuo-2.3-Fast`	2.3 的更快、更便宜的版本

两者默认 768P 和 6 秒。除通用的 0–3600 秒校验外，任务 API 不对这个系列做分辨率或时长范围校验：值会原样转发，由 MiniMax 决定接受或拒绝。控制台操练场提供 768P / 1080P 和 6 或 10 秒，其中 1080P 仅限 6 秒。

请求如何映射（2.3）

信封字段	适配器的处理
`prompt`	作为 `prompt` 发送；存在 `metadata.prompt` 时以它为准
`duration`	作为 `duration` 发送；缺失或为 `0` 时变为 `6`
`size`	按子串转换成 `resolution`：含 `1080` → `1080P`，`768` → `768P`，`720` → `720P`，`512` → `512P`；其它值回退到模型默认
`images` / `image`	不读取。图片输入必须通过 `metadata.first_frame_image` 传入
`ratio`、`generate_audio`、`seconds`	不读取。这个系列没有画面比例或配乐参数
`metadata`	按 MiniMax 的字段名解码成 MiniMax 的字段

这个系列不读取顶层的 resolution：请用 size 或 metadata.resolution。

厂商参数（2.3）

以下字段都放在 metadata 下。JSON 类型错误（例如 "duration": "abc"）会让转换失败并返回 500 build_request_failed，而不是 400；未知键会被忽略。

字段	类型	说明
`resolution`	string	`768P` 或 `1080P`；覆盖由 `size` 换算出的值
`duration`	integer	6 或 10 秒；覆盖顶层 `duration`
`first_frame_image`	string	首帧图像（公网 URL 或 base64 的 `data:` URI），按原样转发
`last_frame_image`	string	首尾帧生视频的尾帧图像，按原样转发
`subject_reference`	array	主体参考生视频的主体参考：`[{"type": "character", "image": ["<url>"]}]`
`prompt_optimizer`	boolean	是否让 MiniMax 改写 prompt；显式 `false` 也会转发
`fast_pretreatment`	boolean	MiniMax 快速预处理开关，按发送值转发
`aigc_watermark`	boolean	是否添加供应商 AIGC 水印
`callback_url`	string	转发给 MiniMax。RouteAPI 不注册也不接收回调，请轮询结果
`prompt`	string	覆盖顶层 `prompt`

metadata.model 会被覆盖成渠道的上游模型名，因此无法通过 metadata 切换到其它（比如更贵的）模型。

图生视频（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"
    }
  }'

状态映射（2.3）

MiniMax v1 返回 Preparing、Queueing、Processing、Success 和 Fail。

上游状态	任务记录状态	进度
`Preparing`、`Queueing`	`IN_PROGRESS`	`30%`
`Processing`	`IN_PROGRESS`	`50%`
`Success`	`SUCCESS`	`100%`
`Fail`	`FAILURE`	`100%`

成功时适配器会用返回的 file_id 调用 MiniMax 的文件查询接口，把拿到的下载地址存进 result_url。该地址会按 MiniMax 的策略过期；GET /v1/videos/{task_id}/content 会把已保存的地址经 RouteAPI 转发，需要带 Authorization。

计费（2.3）

2.3 系列按控制台配置的任务单价计费。你发送的分辨率和时长不影响扣费，完成时也没有差额结算；失败的任务退回预扣额度。X-New-Api-Other-Ratios 为 {}。

错误（2.3）

状态码	`code`	含义
400	`invalid_request`	`prompt` 缺失或为空，或 JSON 格式错误
400	`invalid_seconds`	`duration` / `seconds` 为负或大于 3600
400	MiniMax 的数字业务码	MiniMax 拒绝了任务，文案是其 `status_msg`
400	`task_not_exist`	`task_id` 未知或属于其它账户
500	`build_request_failed`、`do_request_failed`	metadata 转换失败，或上游不可达
500	`unmarshal_response_body_failed`	MiniMax 返回了适配器无法识别的结构
502	`upstream_task_id_missing`	提交响应里没有任务 ID
上游状态码	`fail_to_fetch_task`	MiniMax 返回了非 200 的 HTTP 状态码

这个系列的所有 MiniMax 业务拒绝都返回 400，包括限流；数字 code 和 status_msg 会原样透出，所以请看数字错误码而不是 HTTP 状态码。例外是上游余额不足：当 MiniMax 的 status_msg 命中 RouteAPI 内置的计费关键词（余额不足等）时，响应会被清洗为 503 get_channel_failed 并给出通用文案，同时记为渠道故障（只有在开启自动禁用、且该渠道允许自动禁用时才会自动禁用该渠道）。

提交之后发生的失败（审核不通过、供应商超时）会以 FAILURE 连同 fail_reason 出现在任务记录中，预扣金额退回。