订阅

我把 MiniMax Music 封装成了一个 Agent Skill:一句话生成歌曲、纯音乐和翻唱

· 约 5 分钟 · Python
我把 MiniMax Music 封装成了一个 Agent Skill:一句话生成歌曲、纯音乐和翻唱

最近我整理并开源了一个 MiniMax Music Skill,让 Codex 等支持 Agent Skills 的 AI 编程助手,可以直接根据自然语言生成音乐。

项目地址:https://github.com/SJCZL/skill-music

它目前支持:

  • 根据一句话自动写词并生成歌曲
  • 使用自己编写的歌词生成音乐
  • 生成没有人声的纯音乐
  • 根据本地音频或音频 URL 制作翻唱版本
  • 自动下载生成结果并保存到本地

整个项目不保存 API Key,所有凭据都通过环境变量读取。

为什么要做这个 Skill?

直接调用音乐生成 API 并不算复杂,但每次使用时都需要重复处理很多事情:

  • 整理音乐风格、情绪、乐器和人声提示词
  • 判断是否需要自动生成歌词
  • 区分歌曲、纯音乐和翻唱模式
  • 拼装 API 请求参数
  • 处理返回的音频链接或十六进制数据
  • 在临时链接过期前下载音频
  • 统一文件命名和保存位置

把这些步骤封装成 Skill 后,只需要告诉 Agent 想要什么样的音乐,剩下的参数整理、接口调用和文件下载都可以自动完成。

例如:

使用 $minimax-music 创作一首温暖、治愈的中文流行歌曲, 女声演唱,以钢琴和弦乐为主,主题是重新出发。

Agent 会将需求整理成适合音乐模型的提示词,然后调用脚本生成并保存音频。

项目结构

skills/minimax-music/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── requirements.txt
└── scripts/
    └── run.py

其中:

  • SKILL.md 描述 Skill 的触发条件和工作流程
  • openai.yaml 提供 Codex 中显示的名称和默认提示词
  • run.py 负责调用 MiniMax API、处理响应和保存音频
  • requirements.txt 管理 Python 依赖

支持哪些音乐生成方式?

1. 自动写词并生成歌曲

只需要提供音乐风格,脚本会启用 lyrics_optimizer,让模型自动完成歌词和歌曲生成。

python3 skills/minimax-music/scripts/run.py \
  '{"prompt":"Mandopop, warm and hopeful, female vocal, piano and strings"}'

这种方式适合快速生成主题曲、短视频配乐或者 Demo。

2. 使用自己的歌词

如果已经写好了歌词,可以通过 lyrics 参数直接传入。

python3 skills/minimax-music/scripts/run.py \
  '{"prompt":"Acoustic folk, intimate, gentle male vocal","lyrics":"[Verse]\nMorning light falls on the road\n[Chorus]\nWe are heading home"}'

歌词支持常见的歌曲结构标签,例如:

[Intro]
[Verse]
[Pre Chorus]
[Chorus]
[Bridge]
[Outro]

这些标签可以帮助模型理解歌曲段落并进行编曲。

3. 生成纯音乐

将 is_instrumental 设置为 true,即可生成没有人声的音乐。

python3 skills/minimax-music/scripts/run.py \
  '{"prompt":"Cinematic ambient, calm, piano and warm pads","is_instrumental":true}'

它很适合生成:

  • 视频背景音乐
  • 产品宣传片配乐
  • 播客片头
  • 游戏场景音乐
  • 冥想或白噪音类内容

4. 根据参考音频制作翻唱

Skill 支持通过本地文件或音频 URL 提供参考音频。

python3 skills/minimax-music/scripts/run.py \
  '{"prompt":"Smooth jazz, late-night lounge, saxophone","audio_path":"/absolute/path/reference.mp3"}'

也可以使用:

{
  "prompt": "Electronic pop, energetic, futuristic",
  "audio_url": "https://example.com/reference.mp3"
}

使用翻唱功能时,请确保对参考音频拥有相应权利或已经获得授权。

安装方法

首先克隆项目:

git clone https://github.com/SJCZL/skill-music.git
cd skill-music

安装 Python 依赖:

python3 -m pip install -r skills/minimax-music/requirements.txt

复制到 Codex Skills 目录:

mkdir -p ~/.codex/skills
cp -R skills/minimax-music ~/.codex/skills/

完成后重启 Codex,让它重新加载 Skill。

配置 MiniMax API Key

API Key 只通过环境变量配置:

export MINIMAX_API_KEY="your-api-key"

可以根据需要修改默认模型和输出目录:

export MINIMAX_MUSIC_MODEL="music-3.0-free"
export MINIMAX_MUSIC_COVER_MODEL="music-cover-free"
export MINIMAX_MUSIC_OUTPUT_DIR="/tmp/minimax-music"

项目默认使用 music-3.0-free,具体可用模型和参数请参考 MiniMax 官方音乐生成文档。

生成结果

生成成功后,脚本会输出一段 JSON:

{
  "success": true,
  "message": "音乐生成成功",
  "file_path": "/tmp/minimax-music/20260727_120000.mp3"
}

Agent 可以直接读取 file_path,在支持本地媒体展示的客户端里提供播放入口。

接口返回的音频链接可能存在有效期,因此脚本会立即下载音频,而不是只把临时 URL 返回给用户。

API Key 安全

这个项目在设计时专门处理了凭据安全问题:

  • API Key 只从 MINIMAX_API_KEY 环境变量读取
  • 不在日志中输出 Authorization 请求头
  • 不在 JSON 结果中回显 API Key
  • .gitignore 会忽略 .env、私钥和证书文件
  • 默认忽略生成的 MP3、WAV、FLAC 等音频文件

建议不要把真实 Key 直接写进命令历史、README 或代码文件。如果怀疑 Key 已经泄露,应立即前往 MiniMax 控制台撤销并重新创建。

写在最后

Agent Skill 的价值并不只是把一条 API 请求包装起来,而是把完整、重复的工作流程交给 Agent:

自然语言需求
    ↓
整理音乐提示词
    ↓
选择歌曲、纯音乐或翻唱模式
    ↓
调用 MiniMax Music API
    ↓
下载并保存音频
    ↓
把本地文件交付给用户

如果你也在使用 Codex,或者正在尝试让 AI Agent 参与内容生产,可以安装这个 Skill 体验一下。

项目地址:GitHub:SJCZL/skill-music

欢迎提交 Issue、改进建议或者 Pull Request。