MiniMax H3 SH

MiniMax H3 SH 提供文生视频、首尾帧图生视频和多模态参考生视频三个独立模型，支持原生立体声及 3–15 秒输出。

模型与端点

模型 ID	模式
`minimax-h3-sh/text-to-video`	文生视频
`minimax-h3-sh/image-to-video`	图生视频
`minimax-h3-sh/reference-to-video`	参考生视频

三个模型均调用 POST https://api.aivideoapi.ai/v1/videos/generations。请求体包含 model、input 和可选的 callback_url。

通用输入参数

字段	类型	必填	说明
`prompt`	string	是	非空提示词，描述画面、运动和声音
`resolution`	string	否	`480p`、`540p`、`768p` 或 `1080p`，默认 `480p`
`duration`	integer	否	3–15 秒整数，默认 `5`
`seed`	integer	否	可选，`-1` 至 `9007199254740991` 的安全整数；`-1` 表示随机

文生和参考生还支持 aspect_ratio：16:9（默认）、9:16、1:1、4:3、3:4、21:9 或 9:21。图生视频跟随首帧图片比例，不接受 aspect_ratio。

请使用下面的统一素材字段，不要传 image、last_image、reference_images、reference_videos 或 reference_audios。所有素材均需使用可访问的公网 HTTP(S) URL。时长必须是 JSON 整数；字符串、小数以及 3–15 范围以外的值会在扣款前拒绝。

文生视频

模型为 minimax-h3-sh/text-to-video，填写提示词和输出设置即可。该模型不接受参考素材。

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-sh/text-to-video",
    "input": {
      "prompt": "缓慢跟拍镜头穿过阳光照耀的森林。声音：鸟鸣和轻柔的风声。",
      "resolution": "480p",
      "duration": 5,
      "aspect_ratio": "16:9",
      "seed": -1
    }
  }'

图生视频与首尾帧

模型为 minimax-h3-sh/image-to-video，必须传入包含 1–2 个 URL 的 image_urls。第一张为首帧，可选的第二张为尾帧，两张帧图片均免费。该模式不接受视频、音频参考或 aspect_ratio。

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-sh/image-to-video",
    "input": {
      "prompt": "镜头向前移动，日光逐渐照亮房间。声音：安静的室内环境音。",
      "image_urls": ["https://example.com/first.png", "https://example.com/last.png"],
      "resolution": "768p",
      "duration": 8
    }
  }'

参考生视频

模型为 minimax-h3-sh/reference-to-video，至少提供一种参考图片、视频或音频。

字段	类型	数量上限	说明
`image_urls`	string[]	9	参考图片，每张 4 积分
`video_urls`	string[]	3	MP4/MOV 参考视频，服务端探测时长用于计费
`audio_urls`	string[]	3	独立音频，每段 4 积分，每段最多使用 15 秒

参考视频共用 15 秒处理预算，较长输入会被接受并在多个参考之间分配截取时长。视频自带的音轨会自动使用，不另收独立音频费用。

提示词使用 <Picture 1> 至 <Picture 9>、<Video 1> 至 <Video 3>、<Audio 1> 等标记引用素材，各类型按输入顺序编号。视频音轨占用最前面的音频编号，独立音频从其后继续编号；引用视频自带的声音时可直接使用对应视频标记。

curl -X POST https://api.aivideoapi.ai/v1/videos/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-h3-sh/reference-to-video",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "prompt": "使用 <Picture 1> 中的人物和 <Video 1> 的镜头运动。声音：轻柔的城市环境音。",
      "image_urls": ["https://example.com/character.png"],
      "video_urls": ["https://example.com/movement.mp4"],
      "audio_urls": [],
      "resolution": "540p",
      "duration": 10,
      "aspect_ratio": "16:9"
    }
  }'

计费

每个积分价值 $0.005。以下为账户倍率前的标准价格。

分辨率	文生 / 图生输出积分/秒	参考生输出或参考视频输入积分/秒
`480p`	8	10
`540p`	12	15
`768p`	16	25
`1080p`	32	50

文生 / 图生：请求输出秒数 × 输出单价。首尾帧图片免费。
参考生：（请求输出秒数 + 参考视频计费秒数）× 参考生单价 + 4 × 图片数量 + 4 × 独立音频数量。
参考视频计费秒数：min(15, 探测时长之和)，按实际秒数求和，保留小数，最多计费 15 秒；没有视频时为零。
原生生成的声音已包含在价格内。参考视频自带的音轨不增加独立音频数量。

例如，10 秒 480p 参考生视频搭配 2 张图片和 5 秒参考视频，费用为 158 积分（$0.79）。5 秒 480p 输出搭配一个 5.167 秒的参考视频，费用为 101.67 积分：(5 + 5.167) × 10。两个这样的参考视频按实际合计 10.334 秒计费，费用为 153.34 积分：(5 + 10.334) × 10。三个这样的参考视频按 15 秒封顶，同样的输出费用为 200 积分。

输出按请求的整数秒数计费。模型帧网格可能让实际成片稍长，例如 5 秒请求得到约 5.2 秒视频；不会因此补扣积分或重新结算输出时长。先将整笔基础费用保留两位小数，再应用账户倍率，最终金额再次保留两位小数。

任务查询与退款

创建响应返回平台任务 ID：

{
  "code": 200,
  "msg": "success",
  "data": { "taskId": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1" }
}

使用相同 Bearer 认证轮询 GET https://api.aivideoapi.ai/v1/tasks/{taskId}。状态包括 pending、processing、completed 和 failed。完成后通过 output.urls 获取视频：

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "completed",
  "model": "minimax-h3-sh/text-to-video",
  "credits_consumed": 40,
  "output": {
    "urls": ["https://file.aivideoapi.ai/videos/example.mp4"]
  }
}

积分在提交前预扣一次，确认失败后只退款一次。提交结果不确定时保留预扣并继续核对；生成成功后，即使视频交付或回调需要重试，也不会退款。成功任务不能因后续异常进入退款流程，不按成片实际时长补扣或退还差价，提交后的任务不支持取消。

回调通知

三个模型均支持回调。创建任务时，在请求体顶层传入 callback_url，与 model、input 同级。回调地址需为公网可访问的 HTTP(S) URL，建议使用 HTTPS。

{
  "model": "minimax-h3-sh/text-to-video",
  "callback_url": "https://your-server.com/webhook",
  "input": {
    "prompt": "阳光照耀的森林，伴随鸟鸣",
    "resolution": "480p",
    "duration": 5
  }
}

任务完成或失败后，平台向该地址发送 JSON 格式的 POST 请求。pending 和 processing 状态不会触发回调。

回调请求头

请求头	说明
`Content-Type`	`application/json`
`X-Event`	`task.completed` 或 `task.failed`
`X-Task-Id`	平台任务 ID，与创建响应的 `data.taskId` 一致
`X-Timestamp`	本次通知发送时间，Unix 时间戳，单位为秒

成功通知

X-Event 为 task.completed，通过 output.urls 获取视频地址。时间字段均为秒级 Unix 时间戳。

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "completed",
  "model": "minimax-h3-sh/text-to-video",
  "credits_consumed": 40,
  "created_at": 1789516800,
  "completed_at": 1789516920,
  "output": {
    "urls": ["https://file.aivideoapi.ai/videos/example.mp4"]
  }
}

失败通知

X-Event 为 task.failed，通过 error 获取错误信息。确认失败的任务会退还预扣积分。

{
  "id": "2e723e68-7a4a-4f38-a27a-8e638f6c44a1",
  "status": "failed",
  "model": "minimax-h3-sh/text-to-video",
  "credits_consumed": 0,
  "created_at": 1789516800,
  "error": {
    "code": "upstream_error",
    "message": "Video generation failed"
  }
}

接收与重试

接收端应在保存通知后及时返回 HTTP 2xx。单次请求超时为 10 秒；连接失败、超时或返回非 2xx 时，平台会安排重试，最多投递 3 次（含首次）：

投递次数	时机
第 1 次	任务完成或失败后
第 2 次	第 1 次失败约 3 分钟后
第 3 次	第 2 次失败约 10 分钟后

重试由定时任务执行，实际发送时间可能稍有延迟。接收端请按任务 id 和事件类型做幂等处理，避免重复通知导致重复执行业务操作。

回调投递失败不会改变视频任务结果，也不会触发成功任务退款。未收到通知时，可调用 GET /v1/tasks/{taskId} 查询结果。更多说明见回调指南。

常见错误码

请求失败时，API 返回 JSON 格式的错误响应：

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

错误码一览

HTTP 状态码	错误码	类型	说明
400	`invalid_request`	invalid_request_error	缺少必填参数或参数无效
401	`invalid_api_key`	authentication_error	API Key 无效、已禁用或已删除
402	`insufficient_credits`	billing_error	积分余额不足，请充值
403	`ip_not_allowed`	permission_error	请求 IP 不在 Key 的白名单中
404	`model_not_found`	invalid_request_error	模型不存在或已停用
404	`task_not_found`	invalid_request_error	任务 ID 不存在
429	`rate_limit_exceeded`	rate_limit_error	请求过于频繁，请降低频率
429	`spend_limit_exceeded`	billing_error	达到 Key 的消费限额（每小时/每天/总量）
500	`internal_error`	api_error	服务器内部错误
503	`upstream_error`	upstream_error	上游 AI 服务返回错误

常见场景

invalid_request (400)

缺少必填字段或参数格式错误时返回。

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

积分不足。可通过 GET /v1/credits 查询余额，前往 Dashboard > Billing 充值。

invalid_api_key (401)

可能原因：

Key 不以 sk- 开头
Key 已被禁用或删除
用户账户已被封禁

upstream_error (503)

上游 AI 服务返回错误，可能原因：

输入内容包含敏感或违规信息
上游服务暂时不可用
请求参数不被上游支持

因上游错误导致任务失败时，预扣积分会自动退还。