🎬 MiniMax-H3 视频生成 API

📋 基本信息

📖 API 端点

📤 上传文件说明

I2V 需要传图片作为首帧、R2V 需要传参考图/视频/音频时，推荐先上传文件再引用 URL，而不是直接传外部链接。

上传文件

POST /v1/files/upload（需 Key，multipart/form-data，字段名 file）

curl -X POST http://47.111.83.139:19180/v1/files/upload \
  -H "Authorization: Bearer <key>" \
  -F "file=@/本地路径/图片.jpg"

返回结果

{
  "filename": "18cdf16b00cd0974.png",
  "original_name": "图片.jpg",
  "file_type": ".png",
  "size": 1659985,
  "url": "http://47.111.83.139:19180/v1/files/18cdf16b00cd0974.png",
  "category": "images"
}

支持的文件类型

在生成视频时引用上传的文件

上传返回的 url 可直接用于 image、ref_images、ref_videos、ref_audios 等参数，不需要再下载。

示例：上传图片后用于 I2V：

# 第一步：上传图片
curl -X POST http://47.111.83.139:19180/v1/files/upload \
  -H "Authorization: Bearer <key>" \
  -F "file=@cat.jpg"
# 返回: {"url": "http://47.111.83.139:19180/v1/files/xxx.jpg"}

# 第二步：用返回的 URL 生成视频
curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_i2v","prompt":"猫在草地奔跑","image":"http://47.111.83.139:19180/v1/files/xxx.jpg"}'

示例：上传参考图用于 R2V：

# 上传多张参考图
curl -X POST http://47.111.83.139:19180/v1/files/upload \
  -H "Authorization: Bearer <key>" \
  -F "file=@face.jpg"
# 返回: {"url": "http://47.111.83.139:19180/v1/files/face_xxx.jpg"}

curl -X POST http://47.111.83.139:19180/v1/files/upload \
  -H "Authorization: Bearer <key>" \
  -F "file=@dress.jpg"
# 返回: {"url": "http://47.111.83.139:19180/v1/files/dress_xxx.jpg"}

# 用上传的 URL 做 R2V
curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_r2v","prompt":"<Picture 1>穿着<Picture 2>的衣服跳舞","ref_images":["http://47.111.83.139:19180/v1/files/face_xxx.jpg","http://47.111.83.139:19180/v1/files/dress_xxx.jpg"]}'

查看上传的文件

上传后返回的 url 可以直接在浏览器打开查看图片，或下载视频/音频。无需 Key。

📋 通用参数（三个模型都支持）

以下参数在 T2V / I2V / R2V 三个模型中用法完全一致，类型、默认值、范围完全相同。

megapixels 分辨率参考表

1 MP = 1024×1024 像素（基数 1024²，不是 1000²）。总像素 = megapixels × 1024 × 1024，再按 aspect_ratio 分配宽高并 rounding 到 32 的倍数。

🎥 文生视频 — minimax_h3_t2v

只需一段文字描述，直接生成视频+音频。最简单的用法。

额外参数：无。T2V 只支持通用参数。

curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_t2v","prompt":"一只白鹤在湖面低飞，水波荡漾，夕阳余晖"}'

🖼️ 图生视频 — minimax_h3_i2v

提供一张图片作为首帧（可选尾帧），生成以该图为起点的视频。支持通用参数 + 以下额外参数：

单图（首帧）生视频：

curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_i2v","prompt":"猫在草地奔跑，阳光明媚","image":"https://.../cat.jpg"}'

首尾帧过渡：

curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_i2v","prompt":"从白天过渡到夜晚","image":"https://.../day.jpg","last_image":"https://.../night.jpg"}'

🎨 参考图生视频 — minimax_h3_r2v

用参考图/视频/音频控制生成视频的人物特征、场景风格、动作、声音。支持通用参数 + 以下额外参数：

标签引用规则

在 prompt 中用 <Picture i>、<Video k>、<Audio j> 引用具体素材。编号从 1 开始，三种类型独立编号。

编号顺序：三种类型独立编号，<Audio> 编号包含 ref_video_audios（视频配乐）+ ref_audios（独立音频）。

使用示例

① 单张参考图 — 人物服装/特征：

curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_r2v","prompt":"一个女孩穿着<Picture 1>中的衣服在花园里跳舞","ref_images":["https://.../dress.jpg"]}'

② 两张参考图 — 人物 + 场景：

curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_r2v","prompt":"<Picture 1>在<Picture 2>风格的花园中散步","ref_images":["https://.../face.jpg","https://.../garden.jpg"]}'

③ 参考视频 + 参考图 — 动作 + 风格：

curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_r2v","prompt":"<Video 1>中的动作，在<Picture 1>风格的场景中","ref_images":["https://.../scene.jpg"],"ref_videos":["https://.../dance.mp4"]}'

④ 综合参考 — 图 + 视频 + 音频：

curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_r2v","prompt":"<Video 1>中的动作，<Picture 1>穿着<Picture 2>的衣服，背景音乐参考<Audio 1>","ref_images":["https://.../face.jpg","https://.../clothes.jpg"],"ref_videos":["https://.../dance.mp4"],"ref_audios":["https://.../music.mp3"]}'

⑤ 多图 + 多视频 + 多音频：

curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_r2v","prompt":"<Picture 1>穿着<Picture 2>的衣服，在<Picture 3>风格的场景中，做<Video 1>的动作，背景音乐参考<Audio 1>，音效参考<Audio 2>","ref_images":["https://.../face.jpg","https://.../dress.jpg","https://.../room.jpg"],"ref_videos":["https://.../dance.mp4"],"ref_audios":["https://.../bgm.mp3","https://.../sfx.wav"]}'

⑥ 上传参考图并用 R2V 生成（推荐流程）：

# 先上传参考图
curl -X POST http://47.111.83.139:19180/v1/files/upload \
  -H "Authorization: Bearer <key>" \
  -F "file=@参考图.jpg"
# 返回: {"url": "http://47.111.83.139:19180/v1/files/xxx.jpg"}

# 用上传的 URL 做 R2V（参考图自动从 NAS 复制，不走外网下载）
curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_r2v","prompt":"<Picture 1>在跳舞","ref_images":["http://47.111.83.139:19180/v1/files/xxx.jpg"]}'

⑦ 上传视频并用 R2V 生成（推荐流程）：

# 先上传参考视频
curl -X POST http://47.111.83.139:19180/v1/files/upload \
  -H "Authorization: Bearer <key>" \
  -F "file=@参考视频.mp4"
# 返回: {"url": "http://47.111.83.139:19180/v1/files/xxx.mp4"}

# 用上传的 URL 做 R2V，prompt 中用 <Video 1> 标签引用
curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_r2v","prompt":"<Video 1>在玩耍，保持动作和风格","ref_videos":["http://47.111.83.139:19180/v1/files/xxx.mp4"]}'

⑧ 上传音频并用 R2V 生成：

# 先上传参考音频
curl -X POST http://47.111.83.139:19180/v1/files/upload \
  -H "Authorization: Bearer <key>" \
  -F "file=@背景音乐.mp3"
# 返回: {"url": "http://47.111.83.139:19180/v1/files/xxx.mp3"}

# 用上传的 URL 做 R2V，prompt 中用 <Audio 1> 标签引用
curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_r2v","prompt":"<Audio 1>作为背景音乐，人物在跳舞","ref_audios":["http://47.111.83.139:19180/v1/files/xxx.mp3"]}'

⑨ 上传视频+音频，综合参考：

# 上传参考视频
curl -X POST http://47.111.83.139:19180/v1/files/upload -F "file=@舞蹈.mp4"
# 返回: {"url": "http://.../xxx.mp4"}

# 上传参考音频
curl -X POST http://47.111.83.139:19180/v1/files/upload -F "file=@音乐.mp3"
# 返回: {"url": "http://.../xxx.mp3"}

# 用上传的 URL 做 R2V
curl -X POST http://47.111.83.139:19180/v1/videos/generations \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"minimax_h3_r2v","prompt":"<Video 1>中的动作，背景音乐参考<Audio 1>","ref_videos":["http://.../xxx.mp4"],"ref_audios":["http://.../xxx.mp3"]}'

注意事项

• 用了标签就必须传对应的数组参数：prompt 中写了 <Picture 1> 就必须传 ref_images，写了 <Video 1> 就必须传 ref_videos，写了 <Audio 1> 就必须传 ref_audios
• 标签数量必须与传的参考素材数量匹配（传了 3 张图却用了 <Picture 4> 会报错）
• <Audio> 编号同时包含 ref_video_audios（视频配乐）+ ref_audios（独立音频）
• 标签是参考引导，模型会学习参考图中的特征，但不会完全复制
• 如果不使用任何标签，模型会自动推断参考图的用途（通常用于整体风格参考）
• prompt 的描述文字和标签配合使用效果最佳
• 上传到本服务器的文件会自动走 NAS 内网复制，不需要通过外网下载

⚙️ 枚举值一览

画幅比例 (aspect_ratio)

1:1 (Square)2:3 (Portrait Photo)3:2 (Photo)3:4 (Portrait Standard)4:3 (Standard)9:16 (Portrait Widescreen)16:9 (Widescreen)21:9 (Ultrawide)

采样器 (sampler_name)

eulereuler_ancestralheundpmpp_2mdpmpp_2m_sdedpmpp_sdeddimlcmuni_pcddpm

⚠️ 参数校验与错误说明

参数不合法时，API 返回 HTTP 400，body 包含：

请求过于频繁返回 429（限流 30 秒窗口内最多 600 次）。

常见错误示例

🗣️ 语音合成 TTS — IndexTTS 2.5

高质量语音合成：声音克隆、多语言、情感控制、语速/时长控制。与视频 API 完全独立。

端点

核心参数

基本用法（默认音色）

curl -X POST http://47.111.83.139:19180/v1/audio/speech \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"input":"你好，欢迎使用语音合成服务。","language":"ZH","speed":1.0}'

声音克隆（上传真实音频）

# 第一步：上传参考音频（3~10 秒清晰人声）
curl -X POST http://47.111.83.139:19180/v1/files/upload \
  -H "Authorization: Bearer <key>" \
  -F "file=@参考音频.mp3"
# 返回: {"url": "http://.../v1/files/xxx.mp3"}

# 第二步：用返回的 URL 做声音克隆
curl -X POST http://47.111.83.139:19180/v1/audio/speech \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"input":"这是用真实声音克隆的语音。","language":"ZH","voice_url":"http://47.111.83.139:19180/v1/files/xxx.mp3"}'

情感控制（三种模式）

8 维情感向量维度：happy开心 / angry愤怒 / sad悲伤 / afraid恐惧 / disgusted厌恶 / melancholic忧郁 / surprised惊讶 / calm平静

① 8维情感向量：

curl -X POST http://47.111.83.139:19180/v1/audio/speech \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"input":"太好了，终于成功了！","language":"ZH","emotion_mode":"vector","emotion_vector":{"happy":0.7,"calm":0.3},"emotion_strength":1.0}'

② 文本描述情感（需 Qwen 模型）：

curl -X POST http://47.111.83.139:19180/v1/audio/speech \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"input":"等了这么久，终于可以出发了。","emotion_mode":"text","emotion_text":"克制但难掩喜悦，声音温柔","emotion_strength":0.85}'

③ 参考音频情感（上传情感音频）：

curl -X POST http://47.111.83.139:19180/v1/files/upload -F "file=@情感音频.mp3"
# 返回 {"url": "http://.../v1/files/emo.mp3"}

curl -X POST http://47.111.83.139:19180/v1/audio/speech \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"input":"虽然经历了很多困难，我们依然看到了希望。","emotion_mode":"reference_audio","emotion_audio_url":"http://.../v1/files/emo.mp3","emotion_strength":0.8}'

目标时长控制

curl -X POST http://47.111.83.139:19180/v1/audio/speech \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"input":"这段语音会适配到五秒。","language":"ZH","target_duration":"native","target_duration_seconds":5.0}'

后处理

curl -X POST http://47.111.83.139:19180/v1/audio/speech \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"input":"这是清晰旁白后处理示例。","postprocess":"clear_narration","postprocess_strength":1.0}'

采样参数（CFM 高级）

curl -X POST http://47.111.83.139:19180/v1/audio/speech \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"input":"高清稳定旁白示例。","diffusion_steps":40,"cfg_rate":0.85,"cfm_temperature":0.8}'

分段与停顿

文本中可用 <pause=0.8> 显式停顿（0.8秒），或 <pause=500ms>。

curl -X POST http://47.111.83.139:19180/v1/audio/speech \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"input":"第一句结束。<pause=0.8>这里停八百毫秒。","pause_preset":"narration"}'

发音控制（多音字/专有词）

curl -X POST http://47.111.83.139:19180/v1/audio/speech \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"input":"小明这个题的答案是多少。","pronunciation":"小明<要求|YAO4 QIU2>这个题的答案是多少。","pronunciation_dictionary":"银行|YIN2 HANG2|ZH\n行长|HANG2 ZHANG3|ZH"}'

质量校验（ASR 自动校对重试）

curl -X POST http://47.111.83.139:19180/v1/audio/speech \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{"input":"带质量校验的生成。","quality_retry_count":2,"quality_asr_backend":"auto","quality_threshold":0.82}'

📋 典型调用流程

1. 提交任务 — POST /v1/videos/generations → 得到 job_id
2. 轮询结果 — 每 2~5 秒请求 GET /v1/videos/generations/{id} 直至 status=completed
3. 下载视频 — 从 data[0].url 获取下载链接（无需 Key）