minimax-tokenplan-music

Generate music using MiniMax music-2.6 model. Supports text-to-music (vocal/instrumental), cover generation, and automatic lyrics generation via lyrics_gener...

Security Scan

The skill appears to implement the described music-generation functionality, but there are inconsistencies (notably how API keys are supplied and instructions that require editing the shipped script) that increase risk and warrant caution.

Purpose & Capability

Name, description, code, and SKILL.md all describe a MiniMax music-generation wrapper and require an API key — this is coherent. However the registry/metadata declares a required env var MINIMAX_API_KEY while the shipped script uses a hard-coded API_KEY constant by default and expects users to edit the script or pass --api-key. Declaring MINIMAX_API_KEY as required but not actually reading os.environ in the script is an inconsistency.

Instruction Scope

SKILL.md instructs users to modify scripts/generate.py (paste API key and BASE_URL into top-level constants) and then delete the init section. Asking users to write secrets directly into a shipped file and to edit/delete parts of the skill is intrusive and error-prone. The runtime instructions also allow reading a user-specified lyrics file or local reference audio (which the script base64-encodes and uploads) — those behaviors are coherent with cover-generation but should be highlighted.

Install Mechanism

The registry lists this as an instruction-only skill with no install spec, which is lower-risk. SKILL.md’s metadata includes an 'install' entry pointing to a download URL, but there is no automated install spec in the registry data. No automatic external downloads or archive extraction are present in the included files.

Credentials

Only one secret is requested (MINIMAX_API_KEY), which is appropriate for a remote API. However the declared required env var (MINIMAX_API_KEY) does not appear to be used by the script (it uses an API_KEY constant and also supports --api-key). The SKILL.md encourages embedding the API key into the file, which is a poor security practice because it stores secrets in cleartext under the workspace. The script will also read local audio files and send their base64 contents to the remote API (expected for cover mode) — users should understand that local file contents will be transmitted to the service.

Persistence & Privilege

always is false and autonomous invocation is allowed (platform default). The skill requests filesystem write and network access which are reasonable for saving generated audio and calling a remote API. It does ask users to edit its own files but does not attempt to modify other skills or system-wide agent settings.

What to consider before installing

This skill appears to do what it claims (wrap MiniMax music generation), but there are some red flags you should consider before installing: - API key handling: The registry/metadata lists MINIMAX_API_KEY as required, but the shipped script defaults to a hard-coded API_KEY and the SKILL.md tells you to paste your key into the script. Do NOT store secrets in plain text under your workspace. Prefer passing the key at runtime with --api-key or ask the maintainer to make the script read MINIMAX_API_KEY from the environment. - Local file upload: If you use cover mode with a local audio file, the script base64-encodes the file and sends it to the remote MiniMax endpoint. Only use local files you are comfortable sending to that service. - File edits and cleanup: The instructions ask you to edit and delete sections of the SKILL.md/generate.py. That is intrusive and easy to do incorrectly; keep backups and check file permissions. - Verify endpoints and trust: Confirm you trust the API host (https://api.minimaxi.com or .io) and the skill source. The SKILL.md contains an install URL in metadata but there is no automated install in the package — treat that as a minor inconsistency and verify downloads manually if used. What would reduce risk: require that the script be changed to read MINIMAX_API_KEY from environment variables (and not instruct users to embed keys in files), or provide clear guidance to pass --api-key at runtime; avoid instructing users to delete documentation sections; and document data sent to the API. If you are unsure, request the maintainer to update the skill so it reads credentials from the environment and do not paste secrets into repository files.

MiniMax Music Generation Skill

前置条件

• Python 3 已安装
• requests 库：pip3 install requests

init

需要初始化以下信息：

第一步：获取 API Key

向用户获取 MiniMax API Key（sk-cp- 开头的 Token Plan key，或普通 API Key）。

如果用户不提供 API Key：保持 USE_FREE_MODEL = True，使用免费模型（music-2.6-free / music-cover-free），RPM 较低但无需付费。

第二步：确认配置

向用户确认：

• API Key 是否正确（如果提供了的话）
• 使用国内（https://api.minimaxi.com）还是海外（https://api.minimaxi.io）节点

第三步：填写配置

获取以上信息后：

1. 修改 scripts/generate.py 顶部的配置常量（API_KEY、BASE_URL），填入实际值
2. 如果用户提供了 API Key → 设置 USE_FREE_MODEL = False
3. 如果用户未提供 API Key → 保持 USE_FREE_MODEL = True
4. 同时更新下方 ## 配置 区段的表格，作为配置记录

第四步：清理

配置填写完成后，删除本 ## init 区段（包括 ### 需要初始化以下信息 的全部内容），仅保留 ## 配置 区段。

---

配置

配置项	值	说明
MINIMAX_API_KEY	<待填入>	初始化时替换为实际 key
BASE_URL	<待填入>	CN: https://api.minimaxi.com / Global: https://api.minimaxi.io
USE_FREE_MODEL	<待填入>	有 API Key: False（付费模型） / 无 API Key: True（免费模型）

---

模型说明

模型	说明	适用场景
music-2.6	文生音乐（付费，高 RPM）	Token Plan 用户
music-2.6-free	文生音乐（免费，低 RPM）	所有用户
music-cover	翻唱（付费，高 RPM）	Token Plan 用户
music-cover-free	翻唱（免费，低 RPM）	所有用户

脚本根据 USE_FREE_MODEL 和 --cover 参数自动选择模型，无需手动指定。

---

快速使用

注意：以下示例中 generate.py 均指 ~/.openclaw/workspace/skills/minimax-tokenplan-music/scripts/generate.py 的完整路径。

1. 文生音乐（自动生成歌词）

当不提供 --lyrics 且不传 --instrumental 时，脚本会自动调用歌词生成 API，根据 prompt 生成歌词后再生成音乐。

SKILL_DIR="~/.openclaw/workspace/skills/minimax-tokenplan-music"
python3 "$SKILL_DIR/scripts/generate.py" \
    --prompt "一首关于夏天海边的轻快情歌"

2. 带歌词的音乐

python3 "$SKILL_DIR/scripts/generate.py" \
    --prompt "独立民谣,忧郁,内省" \
    --lyrics "[verse]
街灯微亮晚风轻抚
影子拉长独自漫步
[chorus]
推开木门香气弥漫
熟悉的角落陌生人看"

3. 从文件读取歌词

python3 "$SKILL_DIR/scripts/generate.py" \
    --prompt "流行,欢快,夏日" \
    --lyrics-file /path/to/lyrics.txt

4. 纯音乐（Instrumental）

python3 "$SKILL_DIR/scripts/generate.py" \
    --prompt "轻快的钢琴曲,治愈,咖啡馆" \
    --instrumental

5. 翻唱（本地参考音频）

python3 "$SKILL_DIR/scripts/generate.py" \
    --prompt "清新女声翻唱" \
    --cover \
    --audio "/path/to/reference.mp3"

6. 翻唱（URL 参考音频）

python3 "$SKILL_DIR/scripts/generate.py" \
    --prompt "翻唱风格描述" \
    --cover \
    --audio "https://example.com/song.mp3"

---

参数说明

参数	必填	说明	默认值
--prompt / -p	条件	音乐风格描述（文生音乐: 1-2000字符；翻唱: 10-300字符）	-
--lyrics / -l	❌	歌词内容，\n 分隔，支持结构标签	自动生成
--lyrics-file	❌	从文件读取歌词（与 --lyrics 互斥）	-
--instrumental	❌	生成纯音乐（无人声）	关闭
--cover	❌	翻唱模式（需提供 --audio）	关闭
--audio / -a	翻唱必填	参考音频: URL 或本地路径（6秒-6分钟，最大50MB）	-
--stream	❌	流式输出（output_format 强制为 hex）	关闭
--output-format	❌	hex（默认）或 url（24小时有效链接）	hex
--sample-rate	❌	采样率: 16000/24000/32000/44100	44100
--bitrate	❌	比特率: 32000/64000/128000/256000	256000
--format / -f	❌	音频格式: mp3/wav/pcm	wav
--aigc-watermark	❌	添加 AIGC 水印（非流式模式）	关闭
--lyrics-optimizer	❌	根据 prompt 自动生成歌词（music-2.6 系列）	关闭
--output / -o	❌	输出路径	自动生成
--api-key	❌	API Key（默认使用文件顶部配置）	-
--base-url	❌	Base URL（默认使用文件顶部配置）	-
--timeout	❌	超时秒数	240

---

歌词结构标签

在歌词中使用以下标签标注歌曲结构：

标签	含义	标签	含义
[Intro]	前奏	[Verse]	主歌
[Pre Chorus]	预副歌	[Chorus]	副歌
[Interlude]	间奏	[Bridge]	桥段
[Outro]	尾奏	[Post Chorus]	后副歌
[Transition]	过渡	[Break]	停顿
[Hook]	记忆点	[Build Up]	铺垫
[Inst]	器乐段	[Solo]	独奏

---

自动歌词生成规则

情况	处理方式
--instrumental	纯音乐，不生成歌词
提供了 --lyrics 或 --lyrics-file	使用用户提供的歌词
--lyrics-optimizer	由 API 根据 prompt 自动生成歌词
以上都不满足（非纯音乐 + 无歌词）	自动调用 lyrics_generation API 生成歌词

例如用户说"创建一首非纯音乐"但没给歌词，脚本会先调用歌词 API 生成完整歌词，再用于音乐生成。

---

工作流总结

文生音乐完整流程

1. 确定模式 → 文生音乐 / 纯音乐 / 翻唱
2. 歌词处理 → 用户提供 / 自动生成 / 纯音乐跳过
3. 选择模型 → music-2.6(-free) / music-cover(-free)
4. 调用 API → 自动处理 HEX 解码
5. 保存文件 → WAV/MP3/PCM 格式

翻唱完整流程

1. 用户提供参考音频 → URL 或本地文件
2. 脚本自动处理 → URL 直接传递 / 本地文件转 base64
3. 选择模型 → music-cover(-free)
4. 调用 API → 生成翻唱音频
5. 保存文件

---

脚本输出格式

调用 generate.py 后，stdout 输出生成结果：

output_format	stdout 输出	示例
hex（默认）	保存后的文件绝对路径	~/.openclaw/media/minimax/music/music-2026-04-11-summer-song.wav
url	音乐的公网 URL（24小时有效）	https://filecdn.minimax.chat/...

所有日志信息（[INFO]、[WARN]、[ERROR]）输出到 stderr，不会混入 stdout。

---

文件存储

• 默认保存到：~/.openclaw/media/minimax/music/（多 Agent 共享目录）
• 文件名格式：music-YYYY-MM-DD-<slug>.<format>
• slug：取 prompt 前20字符，保留中英文数字，空格变 -

---

错误处理

code	含义	处理
0	成功	继续
1002	限流	提醒用户 API 限流中，建议稍后重试
1004	鉴权失败	检查 API Key
1008	余额不足	提醒充值
1026	敏感词	换词后重试
2013	参数异常	检查入参
2049	无效 Key	检查 Key 是否正确

---

注意事项

• HEX 解码：API 返回的 audio 字段是 HEX 编码（不是 base64），脚本自动处理
• 翻唱参考音频：6秒-6分钟，最大50MB，支持 mp3/wav/flac 等格式
• URL 有效期：output_format=url 返回的链接仅 24 小时有效
• 流式限制：流式模式下 output_format 强制为 hex，不支持 AIGC 水印
• 免费模型：*-free 模型对所有用户开放，RPM 较低