byted-music-generate

音乐生成技能

使用 Volcengine Music Generation API 生成音乐。支持人声歌曲、纯音乐背景音乐和 AI 歌词生成。

触发条件

1. 用户想要生成一首歌（提供歌词或文本提示词）
2. 用户需要背景音乐、纯音乐曲目或配乐
3. 用户想要 AI 生成的歌词
4. 用户提到“写歌”“音乐生成”“BGM”“背景音乐”“歌词”

环境变量

支持两种身份验证方式（优先使用网关）：

选项 1：API 网关（推荐）

• ARK_SKILL_API_BASE — API 网关基础 URL
• ARK_SKILL_API_KEY — API 网关身份验证密钥

选项 2：直接使用 AK/SK

• VOLCENGINE_ACCESS_KEY — AccessKey ID
• VOLCENGINE_SECRET_KEY — AccessKey Secret
• 获取方式：Volcengine Console → 账户 → 密钥管理 → 创建密钥

用法

1. 判断用户意图并选择模式（song / bgm / lyrics）。
2. cd 到技能目录：skills/byted-music-generate。
3. 运行脚本。脚本会在内部轮询 API，可能需要几分钟才能完成（歌曲/背景音乐通常需要 1–5 分钟）。
4. 监控执行情况：如果运行时环境将命令转入后台，你必须定期（每 10 秒）读取终端输出，检查脚本是否已完成。脚本会将轮询进度输出到 stderr，并在完成后将单行 JSON 输出到 stdout。
5. 完成后，将 JSON 输出中的 audio_url 或 lyrics 返回给用户。

三种模式

1. song — 人声歌曲

用户提供歌词（Lyrics）或文本提示词（Prompt）来生成一首人声歌曲。

# With text prompt
python scripts/music_generate.py song --prompt "A song about summer at the beach" --genre Pop --gender Female

# With lyrics
python scripts/music_generate.py song --lyrics "[verse]\nMoonlight on the windowsill\nMemories flowing like water\n[chorus]\nYou are my moonlight" --genre Folk --mood "Sentimental/Melancholic/Lonely"

注意：--lyrics 和 --prompt 不能同时使用；歌词优先。如果用户尚未提供歌词，可以先使用 lyrics 模式生成歌词，再将结果传入 song 模式。

2. bgm — 纯音乐背景音乐

用自然语言描述期望的音乐。v5.0 模型不需要 Genre/Mood 参数，只需在 --text 字段中描述所有内容。

python scripts/music_generate.py bgm --text "Relaxed coffee shop ambiance music with piano and guitar" --duration 60

# With song structure segments
python scripts/music_generate.py bgm --text "Epic game soundtrack" --segments '[{"Name":"intro","Duration":10},{"Name":"chorus","Duration":30}]'

3. lyrics — 歌词生成

同步返回（无需轮询）。可独立使用，也可作为 song 模式的预处理步骤。

python scripts/music_generate.py lyrics --prompt "A song about graduation farewell" --genre Folk --mood "Sentimental/Melancholic/Lonely" --gender Female

手动查询任务（超时回退）

python scripts/music_generate.py query --task-id "202601397834584670076931"

模式检测逻辑

User Request
    ↓
Contains "instrumental/BGM/background music/soundtrack"?
    ├─ Yes → bgm mode
    └─ No → Contains "lyrics/write lyrics" and does NOT request audio?
        ├─ Yes → lyrics mode
        └─ No → song mode
            ├─ User provided lyrics → --lyrics
            └─ User only described a theme → --prompt (or lyrics first, then song)

脚本参数

song 模式

参数	必填	描述
--lyrics	二选一	带结构标签的歌词
--prompt	二选一	文本提示词（中文，5-700 个字符）
--model-version	否	v4.0 或 v4.3（默认：v4.3）
--genre	否	音乐流派
--mood	否	音乐情绪
--gender	否	Female / Male
--timbre	否	人声音色
--duration	否	时长（秒）[30-240]
--key	否	调性（仅 v4.3）
--kmode	否	Major / Minor（仅 v4.3）
--tempo	否	速度（仅 v4.3）
--instrument	否	乐器，逗号分隔（仅 v4.3）
--genre-extra	否	次要流派，逗号分隔，最多 2 个（仅 v4.3）
--scene	否	场景标签，逗号分隔（仅 v4.3）
--lang	否	语言（仅 v4.3）
--vod-format	否	wav / mp3（仅 v4.3）
--billing	否	prepaid / postpaid（默认：postpaid）
--timeout	否	最大等待秒数（默认：300）

bgm 模式

参数	必填	描述
--text	是	自然语言描述
--duration	否	时长（秒）[30-120]
--segments	否	歌曲结构片段的 JSON 数组
--version	否	模型版本（默认：v5.0）
--enable-input-rewrite	否	启用提示词改写
--billing	否	prepaid / postpaid（默认：postpaid）
--timeout	否	最大等待秒数（默认：300）

lyrics 模式

参数	必填	描述
--prompt	是	歌词提示词（仅中文，<500 个字符）
--genre	否	音乐流派
--mood	否	音乐情绪
--gender	否	Female / Male

脚本返回信息

脚本会输出包含以下字段的 JSON：

{
    "status": "success | timeout | error",
    "mode": "song | bgm | lyrics | query",
    "task_id": "...",
    "audio_url": "https://...",
    "duration": 46.0,
    "lyrics": "...",
    "error": null
}

将 audio_url 返回给用户，以供下载或播放。URL 的有效期约为 1 年，但用户应尽快保存文件。

错误处理

• 如果脚本引发 PermissionError: Authentication not configured ...，请告知用户配置 API 网关（ARK_SKILL_API_BASE + ARK_SKILL_API_KEY）或直接 AK/SK（VOLCENGINE_ACCESS_KEY + VOLCENGINE_SECRET_KEY）环境变量。将它们写入工作区环境变量文件，然后重试。
• 如果 status 为 "timeout"，任务仍在生成中。向用户提供 task_id 和输出中的手动查询命令。
• 如果版权检查失败（代码 50000001），建议用户丰富描述或增加音频时长，然后重试。

参考资料

• 可用参数值（流派/情绪/音色/乐器等）：references/parameters.md
• Volcengine 音乐生成文档
• API 签名指南