minimax-multimodal-toolkit

MiniMax 多模态工具包

通过 MiniMax API 生成语音、音乐、视频和图像内容——统一支持 MiniMax 多模态用例（音频 + 音乐 + 视频 + 图像）。包含用于自定义语音的语音克隆和语音设计、支持角色参考的图像生成，以及基于 FFmpeg 的媒体工具，用于音频/视频格式转换、拼接、裁剪和提取。

设置与配置

前提条件

brew install ffmpeg jq              # macOS
sudo apt install ffmpeg jq          # Linux (Debian/Ubuntu)
bash scripts/check_environment.sh   # verify environment

无需 Python 或 pip——所有脚本都是纯 bash，使用 curl、ffmpeg、jq 和 xxd。

注意： TTS 语音气泡转换（.mp3 → .opus）需要 ffmpeg。如果没有它，TTS 音频会作为文件附件发送，而不是原生语音气泡。

API 配置

MiniMax 为不同地区提供两个服务端点：

地区	API 主机
中国大陆（中国大陆）	https://api.minimaxi.com
全球（全球）	https://api.minimax.io

在 OpenClaw 中——在技能目录中创建 .env 文件（脚本会自动加载，无需 shell export）：

~/.openclaw/workspace/skills/minimax-multimodal-toolkit/.env

MINIMAX_API_KEY=sk-cp-...
MINIMAX_API_HOST=https://api.minimaxi.com

或者通过 openclaw.json 配置：

"skills": {
  "entries": {
    "minimax-multimodal-toolkit": {
      "env": {
        "MINIMAX_API_HOST": "https://api.minimaxi.com",
        "MINIMAX_API_KEY": "sk-cp-..."
      }
    }
  }
}

在其他环境中——运行任何脚本前设置环境变量：

export MINIMAX_API_HOST="https://api.minimaxi.com"
export MINIMAX_API_KEY="your-key-here"

密钥以 sk-api- 或 sk-cp- 开头，可从 https://platform.minimaxi.com（中国）或 https://platform.minimax.io（全球）获取。

重要——缺少凭据时： 运行任何脚本前，检查是否已设置 MINIMAX_API_HOST 和 MINIMAX_API_KEY。 如果缺少其中任何一项：询问用户所在地区和 API 密钥，然后协助他们使用上述方法之一完成配置。

输出与发送

输出目录

所有生成的文件都必须保存到 Agent 当前工作目录下的 minimax-output/ 中（而不是技能目录）。 每次调用脚本都必须包含明确的 --output / -o 参数，并指向此目录。切勿省略输出参数或依赖脚本默认值。

规则：

1. 运行任何脚本前，确保 Agent 的工作目录中存在 minimax-output/（如有需要，创建目录：mkdir -p minimax-output）
2. 始终使用相对于 Agent 工作目录的绝对路径或相对路径：--output minimax-output/video.mp4
3. 切勿 cd 到技能目录运行脚本——应从 Agent 的工作目录中使用完整脚本路径运行
4. 中间/临时文件（片段音频、视频片段、提取的帧）会自动放置在 minimax-output/tmp/ 中。不再需要时可清理：rm -rf minimax-output/tmp

发送到飞书（原生气泡）

生成任何媒体文件后，都必须使用 message 工具将其作为飞书原生气泡发送：

message action=send media=<file-path>

不要使用 [[reply_to_current]] 发送媒体——始终使用带有 media 参数的 message 工具。

媒体类型	格式	说明
图像	PNG/JPG/WebP	直接发送
视频	.mp4	直接发送
音乐	.mp3	直接发送
TTS / 语音	必须先转换为 .opus	MP3 会作为文件附件发送，而不是语音气泡

TTS 音频——发送原生语音气泡所需的转换：

ffmpeg -i output.mp3 -c:a libopus -b:a 128k -y output.opus
message action=send media=output.opus

套餐限制与配额

重要——生成内容前务必遵守用户的套餐限制。 如果用户的配额已用尽或不足，继续操作前先向他们发出警告。

标准套餐

能力	Starter	Plus	Max
M2.7（聊天）	600 req/5h	1,500 req/5h	4,500 req/5h
Speech 2.8	—	4,000 字符/天	11,000 字符/天
image-01	—	50 张图像/天	120 张图像/天
Hailuo-2.3-Fast 768P 6s	—	—	2 个视频/天
Hailuo-2.3 768P 6s	—	—	2 个视频/天
Music-2.5	—	—	4 首歌曲/天（每首 ≤5 分钟）

高速计划

能力	Plus-HS	Max-HS	Ultra-HS
M2.7-highspeed（聊天）	1,500 req/5h	4,500 req/5h	30,000 req/5h
Speech 2.8	9,000 chars/day	19,000 chars/day	50,000 chars/day
image-01	100 images/day	200 images/day	800 images/day
Hailuo-2.3-Fast 768P 6s	—	3 videos/day	5 videos/day
Hailuo-2.3 768P 6s	—	3 videos/day	5 videos/day
Music-2.5	—	7 songs/day (≤5 min each)	15 songs/day (≤5 min each)

配额关键限制：

• 视频分辨率：仅支持 768P — 所有计划均不支持 1080P
• 视频时长：6s — 所有计划的配额均按 6 秒为单位计算
• 视频配额非常有限（根据计划每天 2–5 条）— 生成视频前务必先向用户确认

主要功能

能力	描述	入口
TTS	支持多种音色和情绪的文本转语音合成	scripts/tts/generate_voice.sh
Voice Cloning	从音频样本（10s–5min）克隆音色	scripts/tts/generate_voice.sh clone
Voice Design	根据文本描述创建自定义音色	scripts/tts/generate_voice.sh design
Music Generation	生成带歌词的歌曲或纯音乐曲目	scripts/music/generate_music.sh
Image Generation	文生图、图生图，支持角色参考	scripts/image/generate_image.sh
Video Generation	文生视频、图生视频、主体参考、模板	scripts/video/generate_video.sh
Long Video	通过交叉淡化转场串联多场景视频	scripts/video/generate_long_video.sh
Media Tools	音频/视频格式转换、合并、剪辑、提取	scripts/media_tools.sh

TTS（文本转语音）

入口：scripts/tts/generate_voice.sh

🎙 音色选择（首次使用）

首次调用 TTS 时，请让用户选择音色。提供以下选项：

推荐：

• chunzhen_xuedi — 纯真学弟（乖巧、干净，适合日常）

其他选项：

voice_id	名称	风格
female-shaonv	少女	活泼年轻
female-yujie	御姐	成熟优雅
female-tianmei	甜美女性	温柔柔和
male-qn-qingse	青涩青年	校园青春
male-qn-badao	霸道青年	傲气强势
badao_shaoye	霸道少爷	霸总感
junlang_nanyou	俊朗男友	阳光温暖

完整列表见 references/tts-voice-catalog.md

设置方法： 用户选择后，记住其选择，并在后续所有 TTS 调用中使用 -v <voice_id>。

重要：单音色与多片段——选择正确的方式

用户意图	方式
单一音色 / 无需多个角色	tts 命令 — 一次调用生成全部文本
多个角色 / 旁白 + 对话	使用 generate 命令和 segments.json

默认行为： 用户仅要求生成语音/音色，且未提及多个音色或角色时，直接使用 tts 命令和一个合适的音色。不要拆分为多个片段，也不要使用多片段流程——只需一次性将完整文本传给 tts。

仅在以下情况下使用多片段 generate：

• 用户明确需要多个音色/角色
• 文本需要将旁白与角色对话分开
• 文本超过 10,000 个字符（每次请求的 API 限制）——此时使用相同音色将文本拆分为多个片段

单音色生成

# Generate TTS with chosen voice
bash scripts/tts/generate_voice.sh tts "你想说的话" -v chunzhen_xuedi -o minimax-output/output.mp3

# Convert to .opus (required for native Feishu voice bubble)
ffmpeg -i minimax-output/output.mp3 -c:a libopus -b:a 128k -y minimax-output/output.opus

# Send as native voice bubble
message action=send media=minimax-output/output.opus

多片段生成（多音色 / 有声书 / 播客）

完整工作流——按顺序完成所有步骤：

1. 编写 segments.json — 将文本拆分为片段并分配音色（参见下方格式和规则）
2. 运行 generate 命令 — 该命令会读取 segments.json，通过 TTS API 为每个片段生成音频，然后将它们合并为一个带交叉淡化效果的输出文件

# Step 1: Write segments.json to minimax-output/
# (use the Write tool to create minimax-output/segments.json)

# Step 2: Generate audio from segments.json — this is the CRITICAL step
# It generates each segment individually and merges them into one file
bash scripts/tts/generate_voice.sh generate minimax-output/segments.json \
  -o minimax-output/output.mp3 --crossfade 200

# Step 3: Convert and send
ffmpeg -i minimax-output/output.mp3 -c:a libopus -b:a 128k -y minimax-output/output.opus
message action=send media=minimax-output/output.opus

不要跳过步骤 2。 仅编写 segments.json 不会产生任何效果——必须运行 generate 命令才能实际生成音频。

音色管理

# List all available voices
bash scripts/tts/generate_voice.sh list-voices

# Voice cloning (from audio sample, 10s–5min)
bash scripts/tts/generate_voice.sh clone sample.mp3 --voice-id my-voice

# Voice design (from text description)
bash scripts/tts/generate_voice.sh design "A warm female narrator voice" --voice-id narrator

音频处理

bash scripts/tts/generate_voice.sh merge part1.mp3 part2.mp3 -o minimax-output/combined.mp3
bash scripts/tts/generate_voice.sh convert input.wav -o minimax-output/output.mp3

TTS 模型

模型	说明
speech-2.8-hd	推荐，自动匹配情绪
speech-2.8-turbo	更快的变体
speech-2.6-hd	上一代，手动设置情绪
speech-2.6-turbo	上一代，更快

segments.json 格式

片段之间的默认交叉淡化时长：200ms（--crossfade 200）。

[
  { "text": "Hello!", "voice_id": "female-shaonv", "emotion": "" },
  { "text": "Welcome.", "voice_id": "male-qn-qingse", "emotion": "happy" }
]

对于 speech-2.8 模型，将 emotion 留空（模型会根据文本自动匹配）。

重要：多片段脚本生成规则（有声书、播客等）

为有声书、播客或任何多角色旁白生成 segments.json 时，必须将旁白文本与角色对白拆分成不同片段，并使用不同的声音。

规则：旁白和对白必须始终拆分为不同片段。

句子 "Tom said: The weather is great today!" 必须拆分为两个片段：

• 片段 1（旁白声音）："Tom said:"
• 片段 2（角色声音）："The weather is great today!"

示例 — 旁白加 2 个角色的有声书：

[
  { "text": "Morning sunlight streamed into the classroom as students filed in one by one.", "voice_id": "narrator-voice", "emotion": "" },
  { "text": "Tom smiled and turned to Lisa:", "voice_id": "narrator-voice", "emotion": "" },
  { "text": "The weather is amazing today! Let's go to the park after school!", "voice_id": "tom-voice", "emotion": "happy" },
  { "text": "Lisa thought for a moment, then replied:", "voice_id": "narrator-voice", "emotion": "" },
  { "text": "Sure, but I need to drop off my backpack at home first.", "voice_id": "lisa-voice", "emotion": "" },
  { "text": "They exchanged a smile and went back to listening to the lecture.", "voice_id": "narrator-voice", "emotion": "" }
]

关键原则：

1. 旁白在全文中使用一致、中性的旁白声音
2. 每个角色使用专属的 voice_id，并在其所有对白中保持一致
3. 在对白边界处拆分——"He said:" 属于旁白，引号中的内容属于角色
4. 不要将旁白文本和角色对白合并成单个片段
5. 对于没有现成 voice_id 的角色，先使用声音克隆或声音设计创建声音，然后在片段中引用创建好的 voice_id

音乐生成

入口：scripts/music/generate_music.sh

重要：纯音乐与歌词——如何选择

场景	模式	操作
视频／语音／播客的背景音乐	纯音乐（默认）	直接使用 --instrumental，不要询问用户
用户明确要求“创作音乐”／“制作歌曲”	先询问用户	询问他们想要纯音乐还是带歌词

为视频或语音内容添加背景音乐时，始终默认使用纯音乐模式（--instrumental）。不要询问用户——背景音乐不应包含人声，以免与主要内容相互干扰。

当用户明确要求将创作／生成音乐作为主要任务时，询问他们想要：

• 纯音乐（只有音乐，没有人声）
• 带歌词（有人声的歌曲——由用户提供歌词，或由你协助创作歌词）

# Instrumental (for BGM or when user chooses instrumental)
bash scripts/music/generate_music.sh \
  --instrumental \
  --prompt "ambient electronic, atmospheric" \
  --output minimax-output/ambient.mp3 --download
message action=send media=minimax-output/ambient.mp3

# Song with lyrics (when user chooses vocal music)
bash scripts/music/generate_music.sh \
  --lyrics "[verse]\nHello world\n[chorus]\nLa la la" \
  --prompt "indie folk, melancholic" \
  --output minimax-output/song.mp3 --download
message action=send media=minimax-output/song.mp3

音乐模型

默认模型：music-2.5

music-2.5 不直接支持 --instrumental。需要纯音乐时，脚本会自动采用变通方案：

• 将歌词设为 [intro] [outro]（空的结构标签，不含实际人声），并在提示词中追加 pure music, no lyrics

这样无需手动干预即可生成纯音乐风格的输出。你始终可以使用 --instrumental，其余部分由脚本处理。

图像生成

入口：scripts/image/generate_image.sh

模型：image-01——根据文本提示词生成照片级真实感图像，并可选择使用角色参考图进行图生图。

重要：模式选择——t2i 与 i2i

用户意图	模式
根据文本描述生成图像（默认）	t2i——文生图
使用角色参考照片生成图像（保持人物一致）	i2i——图生图

**默认行为：**用户要求生成／创建图像，但未提及参考照片时，使用 t2i 模式（默认）。仅当用户提供角色参考图，或明确要求基于现有人物的外貌生成图像时，才使用 i2i 模式。

重要：宽高比——根据用户上下文推断

不要总是默认使用 1:1。请分析用户的请求，并选择最合适的宽高比：

用户意图 / 上下文	推荐比例	分辨率
头像、图标、社交媒体头像、avatar、icon、profile pic	1:1	1024×1024
风景、横幅、桌面壁纸、landscape、banner、desktop wallpaper	16:9	1280×720
传统照片、经典比例、classic photo	4:3	1152×864
摄影作品、杂志封面、photography、magazine	3:2	1248×832
人像竖图、海报、portrait photo、poster	2:3	832×1248
竖版海报、书籍封面、tall poster、book cover	3:4	864×1152
手机壁纸、社交媒体故事、phone wallpaper、story、reel	9:16	720×1280
超宽全景、电影画幅、panoramic、cinematic ultrawide	21:9	1344×576
未指定特定需求 / 不明确	1:1	1024×1024

重要：图像数量——何时生成多张图像

用户意图	数量（-n）
默认 / 请求生成单张图像	1（默认）
用户说“几张”“多张”“一些” / “a few”, “several”	3
用户说“多种方案”“备选” / “variations”, “options”	3–4
用户明确指定数量	使用指定数量（1–9）

文生图示例

# Basic text-to-image
bash scripts/image/generate_image.sh \
  --prompt "A cat sitting on a rooftop at sunset, cinematic lighting, warm tones, photorealistic" \
  -o minimax-output/cat.png
message action=send media=minimax-output/cat.png

# Landscape with inferred aspect ratio
bash scripts/image/generate_image.sh \
  --prompt "Mountain landscape with misty valleys, photorealistic, golden hour" \
  --aspect-ratio 16:9 \
  -o minimax-output/landscape.png
message action=send media=minimax-output/landscape.png

# Phone wallpaper (portrait 9:16)
bash scripts/image/generate_image.sh \
  --prompt "Aurora borealis over a snowy forest, vivid colors, magical atmosphere" \
  --aspect-ratio 9:16 \
  -o minimax-output/wallpaper.png
message action=send media=minimax-output/wallpaper.png

# Multiple variations
bash scripts/image/generate_image.sh \
  --prompt "Abstract geometric art, vibrant colors" \
  -n 3 \
  -o minimax-output/art.png
message action=send media=minimax-output/art.png

# With prompt optimizer
bash scripts/image/generate_image.sh \
  --prompt "A man standing on Venice Beach, 90s documentary style" \
  --aspect-ratio 16:9 --prompt-optimizer \
  -o minimax-output/beach.png
message action=send media=minimax-output/beach.png

# Custom dimensions (must be multiple of 8)
bash scripts/image/generate_image.sh \
  --prompt "Product photo of a luxury watch on marble surface" \
  --width 1024 --height 768 \
  -o minimax-output/watch.png
message action=send media=minimax-output/watch.png

图生图（角色参考）

使用参考照片生成角色相同、场景不同的图像。正面单人肖像通常效果最佳。支持的格式：JPG、JPEG、PNG（最大 10MB）。

# Character reference — place same person in a new scene
bash scripts/image/generate_image.sh \
  --mode i2i \
  --prompt "A girl looking into the distance from a library window, warm afternoon light" \
  --ref-image face.jpg \
  --aspect-ratio 16:9 \
  -o minimax-output/girl_library.png
message action=send media=minimax-output/girl_library.png

# Multiple character variations
bash scripts/image/generate_image.sh \
  --mode i2i \
  --prompt "A woman in a red dress at a gala event, elegant, cinematic" \
  --ref-image face.jpg -n 3 \
  -o minimax-output/gala.png
message action=send media=minimax-output/gala.png

宽高比参考

比例	分辨率	适用场景
1:1	1024×1024	默认、头像、图标、社交媒体
16:9	1280×720	风景、横幅、桌面壁纸
4:3	1152×864	经典照片、演示文稿
3:2	1248×832	摄影、杂志版式
2:3	832×1248	人像竖图、海报
3:4	864×1152	书籍封面、竖版海报
9:16	720×1280	手机壁纸、社交媒体故事 / 短视频
21:9	1344×576	超宽全景、电影画幅

关键选项

选项	描述
--prompt TEXT	图像描述，最多 1500 个字符（必填）
--aspect-ratio RATIO	宽高比（见上表）。根据用户上下文推断
--width PX / --height PX	自定义尺寸，512–2048，必须为 8 的倍数；必须同时指定两者。如果同时设置 --aspect-ratio，则以其为准
-n N	要生成的图像数量，1–9（默认 1）
--seed N	用于复现结果的随机种子。相同种子和参数 → 结果相似
--prompt-optimizer	启用 API 自动优化提示词
--ref-image FILE	i2i 模式的角色参考图像（本地文件或 URL，JPG/JPEG/PNG，最大 10MB）
--no-download	输出图像 URL，而不是下载文件
--aigc-watermark	为生成的图像添加 AIGC 水印

视频生成

重要：单片段还是多片段——选择合适的脚本

用户意图	使用的脚本
默认 / 无特殊要求	scripts/video/generate_video.sh（单片段，6s，768P）
用户明确要求“长视频”“多场景”“故事”或时长 > 10s	scripts/video/generate_long_video.sh（多片段）

**默认行为：**除非用户明确要求长视频或多场景视频，否则始终使用单片段 generate_video.sh，时长为 6s、分辨率为 768P。不要自动拆分为多个片段——标准输出为单个 6s 视频。只有当用户明确需要多场景或更长内容时，才使用 generate_long_video.sh。

入口（单个视频）：scripts/video/generate_video.sh 入口（长视频 / 多场景）：scripts/video/generate_long_video.sh

视频模型限制（必须遵守）

各模型支持的分辨率和时长：

模型	分辨率	时长
MiniMax-Hailuo-2.3	仅支持 768P	6s 或 10s
MiniMax-Hailuo-2.3-Fast	仅支持 768P	6s 或 10s
MiniMax-Hailuo-02	512P、768P（默认）	6s 或 10s
T2V-01 / T2V-01-Director	720P	仅支持 6s
I2V-01 / I2V-01-Director / I2V-01-live	720P	仅支持 6s
S2V-01 (ref)	720P	仅支持 6s

重要规则：

• 默认值：6s + 768P — 计划配额按 6 秒为单位计算；除非用户明确要求 10s，否则使用 6s
• 任何计划均不支持 1080P — Hailuo-2.3/2.3-Fast 始终使用 768P
• 较旧的模型（T2V-01、I2V-01、S2V-01）仅支持 720P、6s

⚠️ 时长与账户计划： MiniMax-Hailuo-2.3 支持 6s 或 10s，但部分账户仅支持 6s。 如果遇到 "token plan not support model, MiniMax-Hailuo-2.3-10s-768p" 错误，请切换为 --duration 6。 尝试生成 10s 视频前，务必先检查用户的计划限制。

重要：提示词优化（生成任何视频前必须遵守）

调用任何视频生成脚本前，必须阅读并应用 references/video-prompt-guide.md 优化用户的提示词。切勿将用户的原始描述直接传入 --prompt。

优化步骤：

1. 应用专业公式：主要主体 + 场景 + 动作 + 镜头运动 + 美学氛围

   • 错误示例："A puppy in a park"
   • 正确示例："一只金毛幼犬在公园里沿着洒满斑驳阳光的草地小径跑向镜头，[跟随] 平滑的跟拍镜头，温暖的黄金时刻光线，浅景深，欢快的氛围"

2. 使用 [指令] 语法添加镜头指令：[推进]、[拉远]、[跟随]、[固定]、[左摇] 等。

3. 添加美学细节：光线（黄金时刻、戏剧性的侧光）、色彩分级（暖色调、电影感）、纹理（尘埃颗粒、雨滴）、氛围（亲密、恢弘、平和）

4. 6-10 秒视频仅保留 1-2 个关键动作，避免事件过多

5. i2v 模式（图生视频）：提示词仅聚焦于动作和变化，因为图像已确定视觉内容。不要重新描述图像中的内容。

   • 错误示例："A lake with mountains"（只是重复图像内容）
   • 正确示例："水面泛起轻柔涟漪，微风吹动远处的树木，[固定] 固定镜头，柔和的晨光，宁静祥和"

6. 多片段长视频：每个片段的提示词都必须独立编写并进行优化。i2v 片段（第 2 段及之后）应描述相对于上一片段结束帧的动作和变化。

# Text-to-video (default: 6s, 768P)
bash scripts/video/generate_video.sh \
  --mode t2v \
  --prompt "A golden retriever puppy bounds toward the camera on a sunlit grass path, [跟随] tracking shot, warm golden hour, shallow depth of field, joyful" \
  --output minimax-output/puppy.mp4
message action=send media=minimax-output/puppy.mp4

# Image-to-video (prompt focuses on MOTION, not image content)
bash scripts/video/generate_video.sh \
  --mode i2v \
  --prompt "The petals begin to sway gently in the breeze, soft light shifts across the surface, [固定] fixed framing, dreamy pastel tones" \
  --first-frame photo.jpg \
  --output minimax-output/animated.mp4
message action=send media=minimax-output/animated.mp4

# Start-end frame interpolation (sef mode uses MiniMax-Hailuo-02)
bash scripts/video/generate_video.sh \
  --mode sef \
  --first-frame start.jpg --last-frame end.jpg \
  --output minimax-output/transition.mp4
message action=send media=minimax-output/transition.mp4

# Subject reference (face consistency, ref mode uses S2V-01, 6s only)
bash scripts/video/generate_video.sh \
  --mode ref \
  --prompt "A young woman in a white dress walks slowly through a sunlit garden, [跟随] smooth tracking, warm natural lighting, cinematic depth of field" \
  --subject-image face.jpg \
  --duration 6 \
  --output minimax-output/person.mp4
message action=send media=minimax-output/person.mp4

长视频（多场景）

多场景长视频由多个片段串联而成：第一个片段通过文生视频（t2v）生成，之后的每个片段都将上一片段的最后一帧作为自己的第一帧（i2v）。片段之间使用交叉淡化转场，以保持画面衔接流畅。默认每个片段时长为 6 秒。

工作流：

1. 片段 1：t2v — 完全根据优化后的文本提示词生成
2. 片段 2 及之后：i2v — 将上一片段的最后一帧设为 first_frame_image，提示词描述该结束状态之后的动作和变化
3. 所有片段通过 0.5s 交叉淡化转场拼接，以消除跳切
4. 可选：叠加 AI 生成的背景音乐

各片段的提示词规则：

• 每个片段的提示词都必须使用专业公式单独优化
• 片段 1（t2v）：完整描述场景，包括主体、场景、镜头和氛围
• 片段 2 及之后（i2v）：聚焦于上一片段结束帧之后的变化和动作。不要重复视觉描述——第一帧已提供这些内容
• 保持视觉一致性：各片段的光线、色彩分级和风格关键词应保持一致
• 每个片段仅涵盖 6 秒的动作，内容应聚焦

# Example: 3-segment story with optimized per-segment prompts (default: 6s/segment, 768P)
bash scripts/video/generate_long_video.sh \
  --scenes \
    "A lone astronaut stands on a red desert planet surface, wind blowing dust particles, [推进] slow push in toward the visor, dramatic rim lighting, cinematic sci-fi atmosphere" \
    "The astronaut turns and begins walking toward a distant glowing structure on the horizon, dust swirling around boots, [跟随] tracking from behind, vast desolate landscape, golden light from the structure" \
    "The astronaut reaches the structure entrance, a massive doorway pulses with blue energy, [推进] slow push in toward the doorway, light reflects off the visor, awe-inspiring epic scale" \
  --music-prompt "cinematic orchestral ambient, slow build, sci-fi atmosphere" \
  --output minimax-output/long_video.mp4
message action=send media=minimax-output/long_video.mp4

# With custom settings
bash scripts/video/generate_long_video.sh \
  --scenes "Scene 1 prompt" "Scene 2 prompt" \
  --segment-duration 6 \
  --resolution 768P \
  --crossfade 0.5 \
  --music-prompt "calm ambient background music" \
  --output minimax-output/long_video.mp4
message action=send media=minimax-output/long_video.mp4

添加背景音乐

bash scripts/video/add_bgm.sh \
  --video input.mp4 \
  --generate-bgm --instrumental \
  --music-prompt "soft piano background" \
  --bgm-volume 0.3 \
  --output minimax-output/output_with_bgm.mp4

模板视频

bash scripts/video/generate_template_video.sh \
  --template-id 392753057216684038 \
  --media photo.jpg \
  --output minimax-output/template_output.mp4

视频模型

模式	默认模型	默认时长	默认分辨率	备注
t2v	MiniMax-Hailuo-2.3	6s	768P	最新的文本转视频
i2v	MiniMax-Hailuo-2.3	6s	768P	最新的图像转视频
sef	MiniMax-Hailuo-02	6s	768P	起始帧和结束帧
ref	S2V-01	6s	720P	主体参考，仅支持 6s

媒体工具（音频/视频处理）

入口：scripts/media_tools.sh

基于 FFmpeg 的独立工具，可用于格式转换、拼接、提取、剪辑和音频叠加。当用户需要处理现有媒体文件，而不通过 MiniMax API 生成新内容时，请使用这些工具。

视频格式转换

# Convert between formats (mp4, mov, webm, mkv, avi, ts, flv)
bash scripts/media_tools.sh convert-video input.webm -o output.mp4
bash scripts/media_tools.sh convert-video input.mp4 -o output.mov

# With quality / resolution / fps options
bash scripts/media_tools.sh convert-video input.mp4 -o output.mp4 \
  --crf 18 --preset medium --resolution 1920x1080 --fps 30

音频格式转换

# Convert between formats (mp3, wav, flac, ogg, aac, m4a, opus, wma)
bash scripts/media_tools.sh convert-audio input.wav -o output.mp3
bash scripts/media_tools.sh convert-audio input.mp3 -o output.flac \
  --bitrate 320k --sample-rate 48000 --channels 2

视频拼接

# Concatenate with crossfade transition (default 0.5s)
bash scripts/media_tools.sh concat-video seg1.mp4 seg2.mp4 seg3.mp4 -o merged.mp4

# Hard cut (no crossfade)
bash scripts/media_tools.sh concat-video seg1.mp4 seg2.mp4 -o merged.mp4 --crossfade 0

音频拼接

# Simple concatenation
bash scripts/media_tools.sh concat-audio part1.mp3 part2.mp3 -o combined.mp3

# With crossfade
bash scripts/media_tools.sh concat-audio part1.mp3 part2.mp3 -o combined.mp3 --crossfade 1

从视频中提取音频

# Extract as mp3
bash scripts/media_tools.sh extract-audio video.mp4 -o audio.mp3

# Extract as wav with higher bitrate
bash scripts/media_tools.sh extract-audio video.mp4 -o audio.wav --bitrate 320k

视频剪辑

# Trim by start/end time (seconds)
bash scripts/media_tools.sh trim-video input.mp4 -o clip.mp4 --start 5 --end 15

# Trim by start + duration
bash scripts/media_tools.sh trim-video input.mp4 -o clip.mp4 --start 10 --duration 8

为视频添加音频（叠加/替换）

# Mix audio with existing video audio
bash scripts/media_tools.sh add-audio --video video.mp4 --audio bgm.mp3 -o output.mp4 \
  --volume 0.3 --fade-in 2 --fade-out 3

# Replace original audio entirely
bash scripts/media_tools.sh add-audio --video video.mp4 --audio narration.mp3 -o output.mp4 \
  --replace

媒体文件信息

bash scripts/media_tools.sh probe input.mp4

脚本架构

scripts/
├── check_environment.sh         # Env verification (curl, ffmpeg, jq, xxd, API key)
├── media_tools.sh               # Audio/video conversion, concat, trim, extract
├── tts/
│   └── generate_voice.sh        # Unified TTS CLI (tts, clone, design, list-voices, generate, merge, convert)
├── music/
│   └── generate_music.sh        # Music generation CLI
├── image/
│   └── generate_image.sh        # Image generation CLI (2 modes: t2i, i2i)
└── video/
    ├── generate_video.sh        # Video generation CLI (4 modes: t2v, i2v, sef, ref)
    ├── generate_long_video.sh   # Multi-scene long video
    ├── generate_template_video.sh # Template-based video
    └── add_bgm.sh              # Background music overlay

参考资料

如需了解详细的 API 参数、语音目录和提示词工程，请阅读以下资料：

• tts-guide.md — TTS 设置、语音管理、音频处理、片段格式、故障排查
• tts-voice-catalog.md — 完整的语音目录，包含 ID、描述和参数参考
• music-api.md — 音乐生成 API：端点、参数、响应格式
• image-api.md — 图像生成 API：文本生成图像、图像生成图像、参数
• video-api.md — 视频 API：端点、模型、参数、镜头指令、模板
• video-prompt-guide.md — 视频提示词工程：公式、风格、图像转视频技巧