MiniMax H3 四种视频模式

需要外部素材 URL 或 New API 中转接入时，使用 H3 V2 兼容入口。下文为原生 V1 接口。

先选择模式

H3 通过 POST /media/generations 创建视频任务。公开模型别名以 Portal 详情为准；不要使用服务实例 ID。

当前 H3 合同支持 768p 和 544p 两档、5–15 秒整数时长、24 FPS 音画同步 MP4。每档只接受服务详情列出的六种固定画布；可用 aspectRatio 选择比例，也可直接使用 outputSizeCode。不要传任意像素、内部帧数、采样步数或插帧参数。

不传新增字段的历史 768p 请求继续按原合同处理。全能参考前 6 张图片按基础单价计费，第 7 张起每增加一张图片，单位积分单价增加 10 积分。

创建请求

先按 快速开始 设置三个环境变量。将下列 JSON 保存为 request.json，替换 model。相同业务请求使用稳定的幂等键。

{
  "model":"<MODEL_ALIAS>",
  "generationMode":"t2v",
  "prompt":"雨后街道，镜头缓慢前移，人物撑伞走过，保留自然雨声",
  "resolutionTier":"768p",
  "orientation":"landscape",
  "aspectRatio":"16:9",
  "seconds":5
}

curl --fail-with-body --max-time 60 "$JUSP_BASE_URL/media/generations" \
  -H "Authorization: Bearer $JUSP_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-stable-business-request-id' \
  --data-binary @request.json --output create.json

图生视频完整请求

先上传图片，保存首图 ID（也可把 input_image_asset_id 换成公网地址 input_image_url，见直接使用公网 URL），再将以下完整 JSON 保存为 request.json，沿用上面的提交命令：

{"model":"<MODEL_ALIAS>","generationMode":"i2v","prompt":"保持首图人物和场景，镜头缓慢推进","input_image_asset_id":"<IMAGE_ASSET_ID>","resolutionTier":"768p","orientation":"landscape","seconds":5}

首尾帧完整请求

两张图均需提前上传，不把本地路径放进 JSON：

{"model":"<MODEL_ALIAS>","generationMode":"first_last_frame_video","prompt":"从首图自然过渡到尾图，人物动作连贯","input_image_asset_id":"<START_IMAGE_ASSET_ID>","end_image_asset_id":"<END_IMAGE_ASSET_ID>","resolutionTier":"768p","orientation":"landscape","seconds":5}

全能参考

以下是全能参考完整请求；三类素材均需提前上传。只用图片时删除视频和音频两项，不填空 ID：

{
  "model":"<MODEL_ALIAS>",
  "generationMode":"universal_reference_video",
  "prompt":"保持参考图的主体，参考视频的运镜与参考音频的节奏",
  "resolutionTier":"768p",
  "orientation":"landscape",
  "seconds":5,
  "referenceInputs":[
    {"role":"reference_image","mediaType":"image","assetId":"<IMAGE_ASSET_ID>"},
    {"role":"reference_video","mediaType":"video","assetId":"<VIDEO_ASSET_ID>"},
    {"role":"reference_audio","mediaType":"audio","assetId":"<AUDIO_ASSET_ID>"}
  ]
}

将完整请求保存为 request.json，沿用创建命令。参考顺序有意义：图片、视频、音频分别有序，不重复同一个素材。提示词可明确每项素材的用途。

V1 与 V2 使用同一角色素材限制，该表统一列出格式、字节、解码像素、尺寸、时长和宽高比边界。首尾帧与全能参考图片的文件大小、长边上限不同，首尾帧也不套用全能参考的宽高比限制；请按所选模式和角色校验。

文件字节数与媒体时长须分别满足限制；请求 seconds 的5–15秒是输出时长。MOV 音频参考必须按 audio 上传身份处理，且有有效音轨，不占视频参考名额；参考视频自带音轨不计入独立音频总长。上传成功只表示已暂存，通过上传与错误处理说明了解最终按角色校验的要求。

默认智能优化与费用

只需创建一次生成任务，无需额外调用优化接口。使用 Account API Key 创建 H3 四种模式任务时，optimizePrompt 缺省为 true。平台先优化提示词，成功后才生成视频；创建仍返回异步 Job。只接受 JSON 布尔值，null、字符串和数字会被拒绝。其他模型不会因省略字段自动开启优化。

平台尚未启用自动优化能力时，H3 缺省或 optimizePrompt: true 请求返回 503 prompt_optimization_capability_unavailable。此时不会按原文自动生成；需要直接使用已确认文本时显式传 false，仍需满足正常生成审核与规格要求。默认优化示例以平台已启用该能力为前提。

如果已准备好最终提示词，或已独立调用优化接口并人工采用结果，请显式关闭，避免重复优化及费用：

{"model":"<MODEL_ALIAS>","generationMode":"t2v","prompt":"人工确认的最终提示词","optimizePrompt":false,"resolutionTier":"768p","orientation":"landscape","seconds":5}

false 的优化调用和优化费用均为零，视频生成仍按正常价格计费并经过内容安全审核。开启时，优化和视频生成分别计费；最多两次常规优化尝试，每次完整超长候选最多再压缩一次，合计最多四次优化模型调用，按实际用量计费。已经执行的优化调用即使最终失败也可能收费。

已知可重试技术失败会重试一次，再失败时 Job 返回 failed 和 errorCode: prompt_optimization_failed，保留原文且不自动生成。安全拒绝、需要澄清和候选拒绝不通过重试寻找放行。完整费用、人工采用流程及未知结果恢复见优化教程。个人创作保持人工采用流程；App 的 H3 默认优化及关闭方式见内部应用开发中的平台服务教程。

自动优化的错误会区分原因：准备超时为 prompt_optimization_timeout；内容审核未通过为 content_safety_blocked；需要补充说明为 content_safety_requires_clarification；优化稿被拒绝为 prompt_optimization_candidate_rejected；审核服务暂不可用为 content_safety_unavailable。这些错误发生于 failureStage: prompt_optimization，安全相关原因的 phase 为 content_safety。技术失败继续使用 prompt_optimization_failed。响应说明视频生成尚未开始，优化费用仍按实际调用结算。

查询 HTTP 200 仅表示查询成功，必须检查正文 status、errorCode、errorMessage；有 details 时可显示受控的审核原因和操作指导。retryable: false 表示不要自动新建付费任务。恢复查询保留原失败原因。

查询与恢复

202 返回后按 任务查询 继续。用原 Key 访问原 jobUrl，完成后从 outputs[] 下载。客户端等待结束不取消任务，不要换键重新生成。