视频 API · 独立接入文档

MiniMax—H3接入

使用 SalpX API Key 创建、查询和下载视频。支持文生视频、首尾帧与多模态参考生成，5–15 秒，576P / 768P，横屏、竖屏和方形。

模型 minimax-h3Base URL https://www.salpx.com/v1鉴权 Bearer API Key

minimax-h3 为 SalpX 调用别名。每次生成 1 条视频，10 Step 起步，可选 10–20 Step。支持 t2va 文生视频、fl2va 首尾帧和 ref2va 多模态参考；参考图片、视频和音频可按下方限制组合上传。

生产推荐：576P · 5 秒 · 10 Step · 16:9（1024x576）。按默认组价格计算，此配置生成 1 条视频为 0.35 元。

价格说明

576P、10 Step 基础价：0.07 元/秒，量大可谈。费用随输出时长、分辨率和 Step 调整。

默认组费用（元） = 0.07 × 输出秒数 × 视频数 × 分辨率倍率 ×（Step ÷ 10）

计费参数	取值
输出时长	5–15 秒，按请求的输出秒数计算
视频数	当前每次 1 条
分辨率倍率	576P：1；768P：5/3
Step	10–20 的整数，默认 10；20 Step 费用为同规格 10 Step 的 2 倍

费用示例

分辨率	时长	Step	视频数	默认组费用
576P	5 秒	10	1	0.35 元
768P	5 秒	10	1	约 0.5833 元
576P	5 秒	20	1	0.70 元
768P	5 秒	20	1	约 1.1667 元

示例中的约数为完整公式计算后四舍五入至小数点后 4 位的展示值。768P 使用精确倍率 5/3 参与计算，不先将每秒价格取整或四舍五入。其他分组按该分组的计费倍率计算。

三种生成模式使用相同计费公式，参考素材不另收费。只按视频输出时长计费，排队时间不计费。提交时预扣费用；任务明确失败后退回。网络超时或提交结果未确认时，预扣费用保留待核实，请先查询已有任务，避免重复生成。

1. 创建视频

POST /v1/videos。所有创建、查询和下载请求均使用 Authorization: Bearer $SALPX_API_KEY。将 SalpX API Key 存入本机环境变量；时长必须显式传入。

下面三种模式均使用 multipart/form-data；cURL 的 -F 自动设置 boundary，请勿手工设置 Content-Type。文生视频也支持 JSON 请求。

文生视频

cURL · t2va

curl https://www.salpx.com/v1/videos \
  -H "Authorization: Bearer $SALPX_API_KEY" \
  -F "model=minimax-h3" \
  -F "prompt=清晨阳光下，木桌上的白色茶杯缓缓升起热气，固定镜头" \
  -F "mode=t2va" \
  -F "seconds=5" \
  -F "resolution=576P" \
  -F "aspectRatio=16:9" \
  -F "steps=10" \
  -F "client_request_id=my-h3-text-0001"

首尾帧生成视频

cURL · fl2va

curl https://www.salpx.com/v1/videos \
  -H "Authorization: Bearer $SALPX_API_KEY" \
  -F "model=minimax-h3" \
  -F "prompt=从首帧自然运动，并准确衔接到尾帧" \
  -F "mode=fl2va" \
  -F "startFrame=@first-frame.png" \
  -F "endFrame=@last-frame.png" \
  -F "seconds=5" \
  -F "resolution=576P" \
  -F "aspectRatio=16:9" \
  -F "steps=10" \
  -F "client_request_id=my-h3-frames-0001"

多模态参考生成视频

cURL · ref2va

curl https://www.salpx.com/v1/videos \
  -H "Authorization: Bearer $SALPX_API_KEY" \
  -F "model=minimax-h3" \
  -F "prompt=结合上传的人物、动作与音频参考，生成连贯自然的视频" \
  -F "mode=ref2va" \
  -F "referenceImages=@character-front.png" \
  -F "referenceImages=@character-side.png" \
  -F "referenceVideos=@motion-reference.mp4" \
  -F "referenceAudios=@ambience-reference.mp3" \
  -F "seconds=5" \
  -F "resolution=576P" \
  -F "aspectRatio=16:9" \
  -F "steps=10" \
  -F "client_request_id=my-h3-reference-0001"

示例中的 @文件名 指向调用机器上的素材。每个新任务使用新的 client_request_id；同一任务重试保持编号、参数、素材内容及顺序一致。

创建接口取得 H3 Job ID 后才返回成功响应。响应中的 id 是 SalpX 任务编号，请保存为 VIDEO_ID，用于查询和下载。创建成功表示生成任务已受理，视频尚需排队或生成。

提交结果未确认：接口返回 HTTP 409、错误码 submission_unknown 时，不能据此认定生成失败。请保存响应中的任务编号并查询状态；预扣费用保留待核实，不要更换 client_request_id 重复提交。持续无法确认时，请提供任务编号联系支持。

2. 查询状态

GET /v1/videos/{VIDEO_ID}。建议间隔数秒轮询，直到 status 为 completed（成功）或 failed（失败），成功后下载视频；排队与生成阶段可能返回 queued 或 in_progress。

cURL · 查询任务

curl "https://www.salpx.com/v1/videos/$VIDEO_ID" \
  -H "Authorization: Bearer $SALPX_API_KEY"

3. 下载视频

任务完成后，使用本人的有效 API Key 下载 MP4。请保存视频到自己的存储。

cURL · 下载 MP4

curl --fail "https://www.salpx.com/v1/videos/$VIDEO_ID/content" \
  -H "Authorization: Bearer $SALPX_API_KEY" \
  -o video.mp4

请求参数

字段	说明
`model`	必填，固定为 `minimax-h3`
`prompt`	必填，1–7000 字符
`seconds`	必填，5–15 的整数；推荐 JSON 使用整数字符串（如 "5"）。也可使用 `duration`，同时传时须一致
`size`	可选，见下表；默认 576P 横屏
`resolution` / `aspect_ratio`（或 `aspectRatio`）	可替代 size 指定清晰度与比例；若同时传入，必须一致
`mode`	可选 `auto`（默认）、`t2va`、`fl2va`、`ref2va`。auto 按上传素材推导；显式模式须与素材一致，ref2va 至少上传一种参考素材
`count`	可省略，固定为 1
`steps`	可选，10–20 的整数，默认 10；费用按 Step ÷ 10 成比例计算
`seed`	可选，0–4294967295 的整数
`client_request_id`	建议提供，同一用户重试同一请求使用同一编号；不同视频不可复用

清晰度	横屏 16:9	竖屏 9:16	方形 1:1
576P	1024x576	576x1024	576x576
768P	1344x768	768x1344	768x768

参考素材限制

ref2va 全部参考素材合计不超过 40 MiB（41,943,040 字节）。建议生产提交合计不超过 10 MB 的素材，以减少上传耗时。超过 10 MB 的提交兼容性尚未完成验证。
参考图片 referenceImages：PNG、JPEG 或 WebP，最多 9 张，每张不超过 32 MiB，同时受全部参考素材总量限制。
参考视频 referenceVideos：MP4 或 MOV，最多 1 个，时长不超过 15 秒。含视频时，最多搭配 2 张图片和 1 个音频。
参考音频 referenceAudios：WAV、MP3 或 M4A，最多 3 个，每个不超过 15 MiB、30 秒；含视频时最多 1 个。
首尾帧 startFrame / endFrame：PNG、JPEG 或 WebP，每张不超过 32 MiB。startFrame 必填，endFrame 可选且不能单独使用；首尾帧不能与参考图片、视频或音频混用。
多文件须重复使用完全相同的字段名，例如两次 referenceImages，按上传顺序发送；不要改写为 referenceImages[]。
素材须通过 multipart 文件字段上传；不接受素材 URL、JSON 中的文件路径或 Base64 字符串。

auto 模式下：无素材选择文生视频，有首帧选择首尾帧，有参考素材选择多模态参考。首尾帧和多模态参考不能混用。

调用注意事项

同一 client_request_id 不要并发提交；等待首次请求返回后，再查询任务状态。
请求超时或返回 submission_unknown 不等于生成失败。先查询已有任务，不要换编号立即重复提交。
查询和下载均需本人有效令牌；无令牌会返回 401。
不符合时长、Step、视频数量或素材限制的请求会被拒绝。
明确失败后退回预扣费用；持续无法确认的任务请提供任务 ID 联系支持核实。

文档更新：2026-09-07。