byted-music-generate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Music Generate Skill

音乐生成Skill

This skill generates music using the Volcengine Music Generation API. It supports vocal songs, instrumental BGM, and AI lyrics generation.

本Skill使用火山引擎音乐生成API生成音乐，支持人声歌曲、器乐BGM以及AI歌词生成。

Trigger Conditions

触发条件

User wants to generate a song (with lyrics or a text prompt)
User needs background music, instrumental tracks, or soundtracks
User wants AI-generated lyrics
User mentions "write a song", "music generation", "BGM", "background music", "lyrics"

用户想要生成歌曲（带歌词或文本提示词）
用户需要背景音乐、器乐音轨或配乐
用户想要AI生成歌词
用户提及“写歌”、“音乐生成”、“BGM”、“背景音乐”、“歌词”

Environment Variables

环境变量

Before using this skill, ensure the following environment variables are set:

```
VOLCENGINE_ACCESS_KEY
```
— AccessKey ID
```
VOLCENGINE_SECRET_KEY
```
— AccessKey Secret

How to obtain: Volcengine Console → Account (top-right) → Key Management → Create Key.

使用本Skill前，请确保已配置以下环境变量：

```
VOLCENGINE_ACCESS_KEY
```
— AccessKey ID
```
VOLCENGINE_SECRET_KEY
```
— AccessKey Secret

获取方式：火山引擎控制台 → 账户（右上角）→ 密钥管理 → 创建密钥。

Usage

使用方法

Determine user intent and select the mode (
```
song
```
/
```
bgm
```
/
```
lyrics
```
).
```
cd
```
to the skill directory:
```
skills/byted-music-generate
```
.
Run the script. The script polls the API internally and may take several minutes to complete (typically 1–5 minutes for song/bgm).
Monitor execution: If the runtime environment moves the command to background, you MUST periodically (every 10 seconds) read the terminal output to check whether the script has finished. The script prints polling progress to stderr and outputs a single JSON line to stdout upon completion.
Once completed, return the
```
audio_url
```
or
```
lyrics
```
from the JSON output to the user.

判断用户意图，选择对应模式（
```
song
```
/
```
bgm
```
/
```
lyrics
```
）。
```
cd
```
进入Skill目录：
```
skills/byted-music-generate
```
。
运行脚本。脚本内部会轮询API，可能需要数分钟才能完成（歌曲/BGM生成通常需要1-5分钟）。
监控执行情况：如果运行环境将命令转入后台运行，你必须定期（每10秒）读取终端输出，检查脚本是否执行完成。脚本会将轮询进度打印到stderr，执行完成后会向stdout输出单行JSON结果。
执行完成后，将JSON输出中的
```
audio_url
```
或
```
lyrics
```
返回给用户。

Three Modes

三种模式

1. song — Vocal Song

1. song — 人声歌曲

User provides lyrics (Lyrics) or a text prompt (Prompt) to generate a vocal song.

bash

undefined

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

bash

undefined

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"


**Note**: `--lyrics` and `--prompt` are mutually exclusive; lyrics takes priority. If the user hasn't provided lyrics, you can first use the `lyrics` mode to generate them, then pass the result to the `song` mode.

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` 优先级更高。如果用户未提供歌词，你可以先使用`lyrics`模式生成歌词，再将结果传入`song`模式。

2. bgm — Instrumental BGM

2. bgm — 器乐BGM

Describe the desired music in natural language. The v5.0 model does not require Genre/Mood parameters — just describe everything in the

--text

field.

bash

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

用自然语言描述想要的音乐。v5.0版本模型不需要流派/情绪参数，所有描述都可以写在

--text

字段中。

bash

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}]'

undefined

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

undefined

3. lyrics — Lyrics Generation

3. lyrics — 歌词生成

Returns synchronously (no polling needed). Can be used standalone or as a pre-step for the

song

mode.

bash

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

同步返回结果（无需轮询）。可单独使用，也可作为

song

模式的前置步骤。

bash

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

Manual Task Query (timeout fallback)

手动任务查询（超时 fallback）

bash

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

bash

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

Mode Detection Logic

模式检测逻辑

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)

用户请求
    ↓
是否包含“器乐/BGM/背景音乐/配乐”？
    ├─ 是 → bgm模式
    └─ 否 → 是否包含“歌词/写歌词”且未请求音频？
        ├─ 是 → lyrics模式
        └─ 否 → song模式
            ├─ 用户提供了歌词 → --lyrics参数
            └─ 用户仅描述了主题 → --prompt参数（或先生成歌词再生成歌曲）

Script Parameters

脚本参数

song mode

song模式

Parameter	Required	Description
`--lyrics`	either	Lyrics with structure tags
`--prompt`	either	Text prompt (Chinese, 5-700 chars)
`--model-version`	no	`v4.0` or `v4.3` (default: v4.3)
`--genre`	no	Music genre
`--mood`	no	Music mood
`--gender`	no	`Female` / `Male`
`--timbre`	no	Vocal timbre
`--duration`	no	Duration in seconds [30-240]
`--key`	no	Musical key (v4.3 only)
`--kmode`	no	`Major` / `Minor` (v4.3 only)
`--tempo`	no	Tempo (v4.3 only)
`--instrument`	no	Instruments, comma-separated (v4.3 only)
`--genre-extra`	no	Secondary genres, comma-separated, max 2 (v4.3 only)
`--scene`	no	Scene tags, comma-separated (v4.3 only)
`--lang`	no	Language (v4.3 only)
`--vod-format`	no	`wav` / `mp3` (v4.3 only)
`--billing`	no	`prepaid` / `postpaid` (default: postpaid)
`--timeout`	no	Max wait seconds (default: 300)

参数	是否必填	说明
`--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 mode

bgm模式

Parameter	Required	Description
`--text`	yes	Natural language description
`--duration`	no	Duration in seconds [30-120]
`--segments`	no	JSON array of song structure segments
`--version`	no	Model version (default: v5.0)
`--enable-input-rewrite`	no	Enable prompt rewriting
`--billing`	no	`prepaid` / `postpaid` (default: postpaid)
`--timeout`	no	Max wait seconds (default: 300)

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

lyrics mode

lyrics模式

Parameter	Required	Description
`--prompt`	yes	Lyrics prompt (Chinese only, <500 chars)
`--genre`	no	Music genre
`--mood`	no	Music mood
`--gender`	no	`Female` / `Male`

参数	是否必填	说明
`--prompt`	是	歌词生成提示词（仅支持中文，<500字）
`--genre`	否	音乐流派
`--mood`	否	音乐情绪
`--gender`	否	`Female` / `Male` （演唱者性别）

Script Return Info

脚本返回信息

The script outputs JSON with the following fields:

json

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

Return the

audio_url

to the user for download or playback. URLs are valid for approximately 1 year, but users should save the file promptly.

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

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年，建议用户及时保存文件。

Error Handling

错误处理

```
PermissionError: VOLCENGINE_ACCESS_KEY ...
```
: Inform the user to configure the environment variables. Write them to the workspace environment variable file, then retry.
```
status: "timeout"
```
: The task is still generating. Provide the user with the
```
task_id
```
and the manual query command from the output.
Copyright check failure (code 50000001): Suggest the user enrich the description or increase the audio duration, then retry.

```
PermissionError: VOLCENGINE_ACCESS_KEY ...
```
：告知用户配置环境变量，将变量写入工作区环境变量文件后重试。
```
status: "timeout"
```
：任务仍在生成中，将
```
task_id
```
和手动查询命令提供给用户。
版权检查失败（错误码50000001）：建议用户丰富描述内容或增加音频时长后重试。

References

参考资料

Available parameter values (Genre/Mood/Timbre/Instrument etc.): references/parameters.md
Volcengine Music Generation Docs
API Signature Guide

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