MiniMax Multimodal Toolkit
Generate voice, music, image, and video content via MiniMax APIs. Pure Python — works on Windows, Mac, and Linux without any third-party dependencies.
Prerequisites
- -
MINIMAX_API_KEY environment variable (starts with sk-) - INLINECODE2 environment variable (optional, default:
https://api.minimaxi.com) - Python 3.6+
- For video duration detection:
ffprobe (optional)
Quick Start
CODEBLOCK0
Or use CLI directly:
CODEBLOCK1
Output Convention
All generated files MUST be saved to minimax-output/ under the agent's working directory.
TTS (Text-to-Speech)
Endpoint: POST /v1/t2a_v2 — returns hex audio, decoded and saved as file.
Models: speech-2.8-hd (recommended, best quality), speech-2.8-turbo (faster), speech-02-hd, INLINECODE10
CODEBLOCK2
Common voice IDs: female-shaonv, male-qn-qingse, male-qn-jingying, presenter_male, presenter_female
Emotions: happy, sad, angry, fearful, disgusted, surprised, calm, fluent, whisper (empty = auto)
Music Generation
Endpoint: POST /v1/music_generation — lyrics required, returns audio URL. Takes 30-300 seconds.
CODEBLOCK3
Image Generation (Text-to-Image)
Endpoint: POST /v1/image_generation — returns image URLs (immediate).
CODEBLOCK4
Aspect ratios: 1:1 (default), 16:9, 4:3, 3:2, 2:3, 3:4, 9:16, INLINECODE34
Image-to-Image Generation
Endpoint: POST /v1/image_generation with image_file — generate new images from a reference.
CODEBLOCK5
Video Generation
Endpoint: POST /v1/video_generation (async) + GET /v1/query/video_generation — polling required.
CODEBLOCK6
Models: MiniMax-Hailuo-2.3 (default), MiniMax-Hailuo-2.3-Fast (i2v), MiniMax-Hailuo-02 (1080P, 10s)
Modes: t2v, i2v, sef (start-end frame), ref (subject reference)
Video Prompt Tips
Main subject + Scene + Movement + Camera motion + Aesthetic. For i2v: describe motion only, don't repeat what's in the image.
Generate & Send to Feishu
Use generate_and_send.py to generate content and prepare for Feishu delivery via the feishu-media skill:
CODEBLOCK7
After generation, the script outputs file paths and feishu-media send instructions. Use the feishu-media skill to actually deliver the content.
Legacy PowerShell Script
The original scripts/minimax-api.ps1 is preserved for backward compatibility but is deprecated. Use the Python scripts instead.
Error Handling
| Error Code | Meaning | Solution |
|---|
| 2061 | Plan doesn't support model | Try speech-02-turbo for TTS |
| 1008 |
Insufficient balance | Top up MiniMax account |
| 2013 | Invalid params | Check required fields |
References
See references/ folder for detailed API docs, voice catalogs, and prompt guides.
MiniMax 多模态工具包
通过 MiniMax API 生成语音、音乐、图像和视频内容。纯 Python — 在 Windows、Mac 和 Linux 上运行，无需任何第三方依赖。
前置条件
- - MINIMAXAPIKEY 环境变量（以 sk- 开头）
- MINIMAXAPIHOST 环境变量（可选，默认值：https://api.minimaxi.com）
- Python 3.6+
- 视频时长检测：ffprobe（可选）
快速开始
bash
加载 Python 模块
import sys; sys.path.insert(0, {skillDir}/scripts); import minimax_api
或直接使用命令行：
bash
python {skillDir}/scripts/minimax_api.py tts Hello world -o minimax-output/hello.mp3
python {skillDir}/scripts/minimax_api.py image A cute cat -o minimax-output/cat.png
输出规范
所有生成的文件必须保存到智能体工作目录下的 minimax-output/ 文件夹中。
文本转语音（TTS）
接口：POST /v1/t2a_v2 — 返回十六进制音频，解码后保存为文件。
模型： speech-2.8-hd（推荐，最佳质量）、speech-2.8-turbo（更快）、speech-02-hd、speech-02-turbo
python
基础 TTS
minimax
api.generatetts(Hello world, output=minimax-output/hello.mp3)
中文特定音色
minimax
api.generatetts(红叶最多情，一舞寄相思, voice_id=female-shaonv, output=minimax-output/greeting.mp3)
带情感
minimax
api.generatetts(Im so happy today!, voice_id=male-qn-qingse, emotion=happy, output=minimax-output/happy.mp3)
常用音色 ID： female-shaonv、male-qn-qingse、male-qn-jingying、presentermale、presenterfemale
情感： happy、sad、angry、fearful、disgusted、surprised、calm、fluent、whisper（空值=自动）
音乐生成
接口：POST /v1/music_generation — 需要歌词，返回音频 URL。耗时 30-300 秒。
python
纯音乐（背景音乐）
minimax
api.generatemusic(soft piano, ambient, peaceful, instrumental=True, output=minimax-output/bgm.mp3)
带歌词的歌曲
minimax
api.generatemusic(
indie folk, melancholic,
lyrics=[verse]\nWalking alone\n[chorus]\nFeeling free,
output=minimax-output/song.mp3
)
图像生成（文本转图像）
接口：POST /v1/image_generation — 返回图像 URL（即时返回）。
python
基础
minimax
api.generateimage(A cute cat on a windowsill, photorealistic, output=minimax-output/cat.png)
带宽高比
minimax
api.generateimage(Mountain landscape, golden hour, aspect_ratio=16:9, output=minimax-output/landscape.png)
多张图像
minimax
api.generateimage(Abstract geometric art, vibrant, count=3, output=minimax-output/art.png)
带提示词优化器
minimax
api.generateimage(A man on Venice Beach, 90s documentary, prompt_optimizer=True, output=minimax-output/beach.png)
宽高比： 1:1（默认）、16:9、4:3、3:2、2:3、3:4、9:16、21:9
图像到图像生成
接口：POST /v1/imagegeneration 带 imagefile 参数 — 从参考图像生成新图像。
python
从本地文件
minimax
api.imageto_image(A girl in a library, minimax-output/face.jpg, output=minimax-output/library.png)
从 URL
minimax
api.imageto_image(Oil painting style, https://example.com/photo.jpg, output=minimax-output/painting.png)
视频生成
接口：POST /v1/videogeneration（异步）+ GET /v1/query/videogeneration — 需要轮询。
python
文本转视频
minimax
api.generatevideo(
A golden retriever puppy runs toward camera, tracking shot, golden hour,
output=minimax-output/puppy.mp4
)
图像转视频（提示词仅关注运动）
minimax
api.generatevideo(
Petals sway in breeze, soft light shifts,
mode=i2v, first_frame=minimax-output/flower.png,
output=minimax-output/flower_video.mp4
)
主体参考（面部一致性）
minimax
api.generatevideo(
A woman walks through a garden, tracking shot,
mode=ref, subject_image=minimax-output/face.jpg,
output=minimax-output/garden.mp4
)
模型： MiniMax-Hailuo-2.3（默认）、MiniMax-Hailuo-2.3-Fast（i2v）、MiniMax-Hailuo-02（1080P，10秒）
模式： t2v、i2v、sef（起始-结束帧）、ref（主体参考）
视频提示词技巧
主体 + 场景 + 运动 + 镜头运动 + 美学。对于 i2v：仅描述运动，不要重复图像中已有的内容。
生成并发送到飞书
使用 generateandsend.py 生成内容并通过 feishu-media 技能准备飞书投递：
bash
生成 TTS 并发送
python {skillDir}/scripts/generate
andsend.py tts Hello --voice female-shaonv --feishu-chat
生成图像并发送
python {skillDir}/scripts/generateandsend.py image A sunset --ratio 16:9 --feishu-chat
设置 FEISHUCHATID 环境变量以避免每次传递 --feishu-chat
export FEISHUCHATID=oc_xxxxx
生成后，脚本输出文件路径和飞书媒体发送指令。使用 feishu-media 技能实际投递内容。
旧版 PowerShell 脚本
原始 scripts/minimax-api.ps1 保留用于向后兼容，但已弃用。请改用 Python 脚本。
错误处理
| 错误码 | 含义 | 解决方案 |
|---|
| 2061 | 套餐不支持该模型 | TTS 尝试使用 speech-02-turbo |
| 1008 |
余额不足 | 为 MiniMax 账户充值 |
| 2013 | 参数无效 | 检查必填字段 |
参考资料
详见 references/ 文件夹中的详细 API 文档、音色目录和提示词指南。
