
Byted Music Generate
- 85 installs
- 411 repo stars
- Updated August 4, 2026
- bytedance/agentkit-samples
byted-music-generate is a skill that generates music, background music, and lyrics through the Volcengine Music Generation API.
About
byted-music-generate calls the Volcengine Music Generation API to create vocal songs, instrumental background music, and AI-written lyrics. A developer runs it when an agent needs to produce a song from a theme prompt or supplied lyrics, generate BGM from a natural-language description, or write lyrics first and feed them into song mode. It polls the API internally and returns an audio_url or lyrics as a single JSON line.
- Generates vocal songs, instrumental BGM, and AI lyrics from a text prompt or supplied lyrics
- Wraps the Volcengine Music Generation API with three modes: song, bgm, lyrics
- Polls the API internally and returns an audio_url or lyrics as JSON
Byted Music Generate by the numbers
- 85 all-time installs (skills.sh)
- Ranked #808 of 1,335 Generative Media skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
byted-music-generate capabilities & compatibility
Requires a Volcengine API gateway key or AccessKey/SecretKey; billing is prepaid or postpaid via Volcengine.
- Capabilities
- music generation · lyrics generation · audio generation
- Use cases
- video generation
- Pricing
- Bring your own API key
What byted-music-generate says it does
Generate music using the [Volcengine Music Generation API](https://www.volcengine.com/docs/84992). Supports vocal songs, instrumental BGM, and AI lyrics generation.
The script polls the API internally and may take **several minutes** to complete (typically 1–5 minutes for song/bgm).
Once completed, return the `audio_url` or `lyrics` from the JSON output to the user.
npx skills add https://github.com/bytedance/agentkit-samples --skill byted-music-generateAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 85 |
|---|---|
| repo stars | ★ 411 |
| Last updated | August 4, 2026 |
| Repository | bytedance/agentkit-samples ↗ |
What it does
Generate a vocal song, instrumental BGM track, or AI lyrics from a text prompt or supplied lyrics.
Who is it for?
Agents that need to produce songs, background music, or lyrics from a prompt or lyrics text.
Skip if: Editing or mixing existing audio files, since it only generates new audio via the API.
When should I use this skill?
The user wants to create a song, background music, a soundtrack, or AI-generated lyrics.
What you get
Returns an audio_url for the generated song or BGM, or the generated lyrics, as JSON.
- A generated song or BGM audio URL
- AI-generated lyrics text
By the numbers
- 3 modes (song, bgm, lyrics)
- song duration range 30-240 seconds
Files
Music Generate Skill
Generate music using the Volcengine Music Generation API. Supports vocal songs, instrumental BGM, and AI lyrics generation.
Trigger Conditions
1. User wants to generate a song (with lyrics or a text prompt) 2. User needs background music, instrumental tracks, or soundtracks 3. User wants AI-generated lyrics 4. User mentions "write a song", "music generation", "BGM", "background music", "lyrics"
Environment Variables
Two authentication methods are supported (gateway takes priority):
Option 1: API Gateway (recommended)
ARK_SKILL_API_BASE— API gateway base URLARK_SKILL_API_KEY— API gateway authentication key
Option 2: Direct AK/SK
VOLCENGINE_ACCESS_KEY— AccessKey IDVOLCENGINE_SECRET_KEY— AccessKey Secret- How to obtain: Volcengine Console → Account → Key Management → Create Key
Usage
1. Determine user intent and select the mode (song / bgm / lyrics). 2. cd to the skill directory: skills/byted-music-generate. 3. Run the script. The script polls the API internally and may take several minutes to complete (typically 1–5 minutes for song/bgm). 4. 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. 5. Once completed, return the audio_url or lyrics from the JSON output to the user.
Three Modes
1. song — Vocal Song
User provides lyrics (Lyrics) or a text prompt (Prompt) to generate a vocal song.
# 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.
2. bgm — Instrumental 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.
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 — Lyrics Generation
Returns synchronously (no polling needed). Can be used standalone or as a pre-step for the song mode.
python scripts/music_generate.py lyrics --prompt "A song about graduation farewell" --genre Folk --mood "Sentimental/Melancholic/Lonely" --gender FemaleManual Task Query (timeout fallback)
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)Script Parameters
song mode
| 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) |
bgm mode
| 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) |
lyrics mode
| Parameter | Required | Description |
|---|---|---|
--prompt | yes | Lyrics prompt (Chinese only, <500 chars) |
--genre | no | Music genre |
--mood | no | Music mood |
--gender | no | Female / Male |
Script Return Info
The script outputs JSON with the following fields:
{
"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.
Error Handling
- IF the script raises
PermissionError: Authentication not configured ..., inform the user to configure either API gateway (ARK_SKILL_API_BASE+ARK_SKILL_API_KEY) or direct AK/SK (VOLCENGINE_ACCESS_KEY+VOLCENGINE_SECRET_KEY) environment variables. Write them to the workspace environment variable file, then retry. - IF
statusis"timeout", the task is still generating. Provide the user with thetask_idand the manual query command from the output. - IF copyright check fails (code 50000001), suggest the user enrich the description or increase the audio duration, then retry.
References
- Available parameter values (Genre/Mood/Timbre/Instrument etc.): references/parameters.md
- Volcengine Music Generation Docs
- API Signature Guide
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.Volcengine Music Generation Parameters
Song Genre (GenSong)
V4.0
| Parameter | 说明 | Parameter | 说明 |
|---|---|---|---|
| Folk | 民谣 | Punk | 朋克 |
| Pop | 流行 | Electronic | 电子 |
| Rock | 摇滚 | Jazz | 爵士 |
| Chinese Style | 国风 | Reggae | 雷鬼 |
| Hip Hop/Rap | 嘻哈 | DJ | DJ |
| R&B/Soul | R&B | Pop Punk | 流行朋克 |
| Disco | 迪斯科 | Future Bass | 未来贝斯 |
| Pop Rap | 流行说唱 | Trap Rap | 陷阱说唱 |
| R&B Rap | 旋律说唱 | Chinoiserie Electronic | 国风电子 |
| GuFeng Music | 古风音乐 | Pop Rock | 流行摇滚 |
| Jazz Pop | 流行爵士 | Bossa Nova | 巴塞诺瓦 |
| Contemporary R&B | 当代节奏布鲁斯 |
V4.3 (Genre & GenreExtra)
| Parameter | 说明 | Parameter | 说明 | Parameter | 说明 |
|---|---|---|---|---|---|
| Blues | 布鲁斯 | Trip Hop | 神游舞曲 | Chinese Folk | 国语民谣 |
| Chinese Opera | 中国戏曲 | Ambient | 氛围电子 | Contemporary Blues | 当代布鲁斯 |
| Chinese Style | 国风音乐 | Deep Pop Edm | 流行电子舞曲 | Contemporary Folk | 当代民谣 |
| Chinese Tradition | 中国传统 | EDM Trap | 陷阱舞曲 | Country Blues | 乡村布鲁斯 |
| Classical | 古典 | Future House | 未来浩室 | Emo Rap | 情绪说唱 |
| Country | 乡村 | China-Wave | 国风流行 | Gangsta Rap | 匪帮说唱 |
| DJ | DJ | GuFeng Music | 古风 | Hardstyle | 硬派舞曲 |
| Easy Listening | 轻音乐 | Chinoiserie Rap | 国风嘻哈 | Melbourne Bounce | 墨尔本弹跳 |
| Electronic | 电子 | Chinoiserie Electronic | 国风电子 | Pop Punk | 流行朋克 |
| Folk | 民谣 | Hard Rock | 硬摇滚 | Rock Blues | 摇滚布鲁斯 |
| Hip Hop/Rap | 嘻哈 | Pop Rock | 流行摇滚 | Thrash Metal | 激流金属 |
| Jazz | 爵士 | Alternative Rock | 另类摇滚 | Traditional Jazz | 传统爵士 |
| MC | 喊麦 | Indie Rock | 独立摇滚 | Breakbeat | 碎拍 |
| Metal | 金属 | Soft Rock | 轻摇滚 | Country Rock | 乡村摇滚 |
| Pop | 流行 | Jazz Pop | 流行爵士 | Jazz Blues | 爵士布鲁斯 |
| Punk | 朋克 | Bossa Nova | 巴塞诺瓦 | Bebop | 波普 |
| R&B/Soul | 节奏蓝调 | Swing | 摇摆乐 | Brit Pop | 英伦流行 |
| Reggae | 雷鬼 | Big Band | 大乐队 | Bubblegum Bass | 泡泡糖贝斯 |
| Rock | 摇滚 | Cool Jazz | 冷爵士 | Chinese Ballad Pop | 国语抒情 |
| 8 Bit | 8 Bit | Trap Rap | 陷阱说唱 | Classical period | 古典主义 |
| Alternative/Indie | 另类独立 | R&B Rap | 旋律说唱 | Classic R&B / Soul | 传统R&B |
| Chinese Pop | 国语流行 | Jazz Hip Hop | 爵士嘻哈 | Dancehall | 舞场雷鬼 |
| Teen Pop | 青少年流行 | Pop Rap | 流行说唱 | Deathcore | 死核 |
| Indie Pop | 独立流行 | Hardcore Rap | 硬核说唱 | Doo-Wop | 嘟喔普 |
| Dream Pop | 梦幻流行 | Hip House | 说唱浩室 | Downtempo | 缓拍 |
| City Pop | 都市流行 | Chill Beats | 弛放节拍 | Grunge Rock | 油渍摇滚 |
| Synth Pop | 合成器流行 | Funk | 放克 | Gypsy Jazz | 吉普赛爵士 |
| Dance Pop | 流行舞曲 | Contemporary R&B | 当代R&B | Hard Bop | 硬波普 |
| Electropop | 电音流行 | Neo Soul | 新灵魂乐 | Hardcore | 硬核 |
| Chamber Pop | 室内流行 | Soul | 灵魂乐 | Modernism | 现代主义 |
| EDM | EDM | Pop Soul | 流行灵魂乐 | Neo Funk | 新放克 |
| House | 浩室舞曲 | Glam Metal | 华丽金属 | Nu Metal | 新金属 |
| Dubstep | 回响贝斯 | Power Metal | 力量金属 | Post-Punk | 后朋克 |
| Future Bass | 未来贝斯 | Gospel | 福音音乐 | Progressive R&B | 前卫R&B |
| Chillout | 驰放 | Traditional Chinese Folk | 传统民歌 | Synthwave | 合成器潮 |
| Trance | 出神舞曲 | Chinese Quyi | 中国曲艺 | Jersey Club | 泽西俱乐部 |
| Drum&Bass | 鼓与贝斯 | Folk Pop | 流行民谣 | Chinoiserie Rock | 国风摇滚 |
| Tropical House | 热带浩室 | Indie Folk | 独立民谣 | Midtempo | 中速节奏 |
| Disco | 迪斯科 | Boombap | 蹦啪说唱 | Kawaii Bass | 可爱贝斯 |
| Vaporwave | 蒸汽波 | Chillwave | 寒潮 |
---
Song Mood
V4.0
| Parameter | 说明 | Parameter | 说明 |
|---|---|---|---|
| Happy | 快乐 | Chill | 放松 |
| Dynamic/Energetic | 活力 | Romantic | 浪漫 |
| Sentimental/Melancholic/Lonely | EMO | Miss | 思念 |
| Inspirational/Hopeful | 鼓舞 | Groovy/Funky | 律动 |
| Nostalgic/Memory | 怀旧 | Dreamy/Ethereal | 梦幻 |
| Excited | 兴奋 | Calm/Relaxing | 平静 |
| Sorrow/Sad | 伤感 |
V4.3
| Parameter | 说明 | Parameter | 说明 |
|---|---|---|---|
| Angry/Aggressive | 生气 | Romantic | 浪漫 |
| Calm/Relaxing | 平静 | Sorrow/Sad | 悲伤 |
| Chill | 放松 | Sweet_SA_MOOD | 甜蜜 |
| Cute/Playful | 可爱 | Thrilling/Suspenseful/Tense | 惊险/悬疑 |
| Dynamic/Energetic | 活力 | Weird | 奇怪 |
| Excited | 兴奋 | Groovy/Funky | 律动 |
| Funny | 有趣 | Nostalgic/Memory | 怀旧 |
| Happy | 快乐 | Dreamy/Ethereal | 梦幻 |
| Healing | 治愈 | Magnificent/Epic | 震撼/壮丽 |
| Inspirational/Hopeful | 鼓舞 | Brisk/Carefree | 轻快 |
| Sentimental/Melancholic/Lonely | 忧郁 | Warm/Kind | 温暖 |
| Miss | 思念 | Confident/Determined | 自信 |
| Mysterious | 神秘 | Lyrical/Ballad | 抒情 |
---
Song Timbre
V4.0
| Parameter | 说明 | Parameter | 说明 |
|---|---|---|---|
| Warm | 温暖 | Sweet_AUDIO_TIMBRE | 甜美 |
| Bright | 明亮 | Cute_AUDIO_TIMBRE | 可爱 |
| Husky | 烟嗓 | Loud and sonorous | 浑厚 |
| Electrified voice | 电音 | Powerful | 高亢 |
| Sexy/Lazy | 慵懒 |
V4.3
| Parameter | 说明 | Parameter | 说明 | Parameter | 说明 |
|---|---|---|---|---|---|
| Warm | 温暖 | Magnetic | 磁性 | Uncle Like | 大叔风 |
| Ethereal | 空灵 | Bel Canto | 美声 | Gritty | 粗犷 |
| Husky | 烟嗓 | Gentle | 温柔 | Romantic_AUDIO_TIMBRE | 浪漫 |
| Deep | 低沉 | Delicate | 细腻 | Enthusiastic | 热情 |
| Extreme | 极端 | Energetic | 热血 | Smoky | 烟嗓 |
| Sharp | 锐利 | Sassy | 自信 | Chinese Opera Tune | 戏腔 |
| Bright | 明亮 | Refreshing | 清新 | Round | 圆润 |
| Powerful | 高亢 | Soothing | 治愈 | Flat | 平淡 |
| Sexy/Lazy | 慵懒 | Comical | 滑稽 | Growling | 嘶吼 |
---
Song Key (V4.3)
A, A#, B, C, C#, Cb, D, D#, E, F, F#, G, Ab
Song Kmode (V4.3)
Major (大调), Minor (小调)
Song Tempo (V4.3)
| Parameter | 说明 | Parameter | 说明 |
|---|---|---|---|
| Grave | 庄板 | Moderato | 中板 |
| Largo | 广板 | Allegro | 快板 |
| Adagio | 慢板 | Vivace | 活泼快板 |
| Andante | 行板 | Presto | 急板 |
Song Instrument (V4.3)
| Parameter | 说明 | Parameter | 说明 | Parameter | 说明 |
|---|---|---|---|---|---|
| Flute | 长笛 | Electric_Piano | 电钢琴 | Electric_Guitar | 电吉他 |
| Saxophone | 萨克斯 | Organ | 风琴 | Clean_Electric_Guitar | 清音电吉他 |
| Brass | 铜管乐器 | Strings | 弦乐 | Distorted_Electric_Guitar | 失真电吉他 |
| Trumpet | 小号 | Violin | 小提琴 | Synthesizers | 合成器 |
| Percussion | 打击乐 | Cello | 大提琴 | Banjo | 班卓琴 |
| Drums | 架子鼓 | Bass | 贝斯 | Congas/Bongos | 非洲手鼓 |
| Keys | 键盘 | Guitar | 吉他 | Acoustic_Piano | 原声钢琴 |
| Acoustic_Guitar | 原声吉他 |
Song Scene (V4.3, 部分列举)
| Parameter | 说明 | Parameter | 说明 | Parameter | 说明 |
|---|---|---|---|---|---|
| Autumn | 秋天 | Party | 聚会 | Game | 游戏 |
| Bedtime | 睡眠 | Sport | 运动 | Love | 爱 |
| Birthday | 生日 | Spring | 春天 | Wedding | 婚礼 |
| Broke up | 失恋 | Summer | 夏天 | Campus | 校园 |
| Coffee Shop | 咖啡厅 | Travel | 旅行 | Christmas | 圣诞 |
| Dance | 跳舞 | Winter | 冬天 | Evening | 夜晚 |
| Dating | 约会 | Meditation | 冥想 | Morning | 早晨 |
| Drive | 开车 | Yoga | 瑜伽 | Graduation | 毕业 |
| Friendship | 友情 | Family | 亲情 | Spring Festival | 春节 |
完整 Scene 列表请参考 可选参数文档
Song Lang (V4.3)
Chinese (普通话), English (英文), Instrumental/Non-vocal (纯器乐)
---
Lyrics Structure Tags
[intro] 前奏
[verse] 主歌
[pre-chorus] 预副歌
[chorus] 副歌
[bridge] 桥段
[inst] 间奏
[outro] 尾奏
[hook] 钩子段落
[build-up] 铺垫
[drop] 电子曲风
[solo] 独奏# Volcengine Music Generation skill dependencies
requests>=2.28.0
# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""
Music generation using Volcengine Imagination API.
Supports: vocal songs (GenSong), instrumental BGM (GenBGM), lyrics (GenLyrics).
Ref: https://www.volcengine.com/docs/84992
Auth: API gateway (Bearer token) or direct AK/SK (HMAC-SHA256).
"""
from __future__ import annotations
import argparse
import hashlib
import hmac
import json
import os
import sys
import time
from datetime import datetime, timezone
from functools import reduce
from typing import Any, Dict, Optional
import requests
API_HOST = "open.volcengineapi.com"
API_VERSION = "2024-08-12"
REGION = "cn-beijing"
SERVICE = "imagination"
POLL_INTERVAL = 10
MAX_WAIT_SECONDS = 300
TASK_STATUS_SUCCESS = 2
TASK_STATUS_FAILED = 3
class VolcEngineApiClient:
"""Volcengine API client supporting API gateway (Bearer) and direct AK/SK (HMAC-SHA256)."""
def __init__(
self,
*,
api_base: str = "",
api_key: str = "",
ak: str = "",
sk: str = "",
):
if api_base and api_key:
self._mode = "gateway"
self._api_base = api_base.rstrip("/")
self._api_key = api_key
elif ak and sk:
self._mode = "aksk"
self._api_base = f"https://{API_HOST}"
self._ak = ak
self._sk = sk
else:
raise ValueError("Either (api_base, api_key) or (ak, sk) must be provided")
def request(self, action: str, body: dict, method: str = "POST") -> dict:
url = f"{self._api_base}/?Action={action}&Version={API_VERSION}"
if self._mode == "gateway":
return self._request_gateway(url, body, method)
return self._request_aksk(url, action, body, method)
def _request_gateway(self, url: str, body: dict, method: str) -> dict:
headers = {
"Content-Type": "application/json; charset=utf-8",
"Authorization": f"Bearer {self._api_key}",
"ServiceName": SERVICE,
}
if method == "GET":
resp = requests.get(url, headers=headers, timeout=30)
else:
resp = requests.post(url, headers=headers, json=body, timeout=30)
if resp.status_code != 200:
raise RuntimeError(f"HTTP {resp.status_code}: {resp.text}")
return resp.json()
def _request_aksk(self, url: str, action: str, body: dict, method: str) -> dict:
json_body = "" if method == "GET" else json.dumps(body, ensure_ascii=False)
ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
body_hash = hashlib.sha256(json_body.encode()).hexdigest()
headers_to_sign = {
"content-type": "application/json; charset=utf-8",
"host": API_HOST,
"x-content-sha256": body_hash,
"x-date": ts,
}
signed_keys = sorted(headers_to_sign.keys())
canonical_headers = "".join(
f"{k}:{headers_to_sign[k]}\n" for k in signed_keys
)
signed_headers = ";".join(signed_keys)
canonical_request = (
f"{method}\n/\n"
f"Action={action}&Version={API_VERSION}\n"
f"{canonical_headers}\n{signed_headers}\n{body_hash}"
)
credential_scope = f"{ts[:8]}/{REGION}/{SERVICE}/request"
string_to_sign = (
f"HMAC-SHA256\n{ts}\n{credential_scope}\n"
f"{hashlib.sha256(canonical_request.encode()).hexdigest()}"
)
signing_key = reduce(
lambda key, msg: hmac.new(key, msg.encode(), hashlib.sha256).digest(),
[ts[:8], REGION, SERVICE, "request"],
self._sk.encode(),
)
signature = hmac.new(
signing_key, string_to_sign.encode(), hashlib.sha256
).hexdigest()
req_headers = {
k.title().replace("X-C", "X-c"): v
for k, v in headers_to_sign.items()
}
req_headers["Authorization"] = (
f"HMAC-SHA256 Credential={self._ak}/{credential_scope}, "
f"SignedHeaders={signed_headers}, Signature={signature}"
)
if method == "GET":
resp = requests.get(url, headers=req_headers, timeout=30)
else:
resp = requests.post(
url, headers=req_headers, data=json_body.encode(), timeout=30
)
if resp.status_code != 200:
raise RuntimeError(f"HTTP {resp.status_code}: {resp.text}")
return resp.json()
def _get_client() -> VolcEngineApiClient:
api_base = os.getenv("ARK_SKILL_API_BASE", "").strip()
api_key = os.getenv("ARK_SKILL_API_KEY", "").strip()
if api_base and api_key:
return VolcEngineApiClient(api_base=api_base, api_key=api_key)
ak = os.getenv("VOLCENGINE_ACCESS_KEY", "").strip()
sk = os.getenv("VOLCENGINE_SECRET_KEY", "").strip()
if ak and sk:
return VolcEngineApiClient(ak=ak, sk=sk)
raise PermissionError(
"Authentication not configured. Set either:\n"
" - ARK_SKILL_API_BASE + ARK_SKILL_API_KEY (API gateway), or\n"
" - VOLCENGINE_ACCESS_KEY + VOLCENGINE_SECRET_KEY (direct AK/SK)"
)
def _get_song_action(mode: str, billing: str) -> str:
actions = {
("song", "prepaid"): "GenSongV4",
("song", "postpaid"): "GenSongForTime",
("bgm", "prepaid"): "GenBGM",
("bgm", "postpaid"): "GenBGMForTime",
}
return actions[(mode, billing)]
def _poll_task(
client: VolcEngineApiClient,
task_id: str,
max_wait: int = MAX_WAIT_SECONDS,
) -> dict:
"""Poll QuerySong until task completes or timeout."""
polls = 0
max_polls = max_wait // POLL_INTERVAL
while polls < max_polls:
time.sleep(POLL_INTERVAL)
polls += 1
resp = client.request("QuerySong", {"TaskID": task_id})
result = resp.get("Result", {})
status = result.get("Status")
print(
f"Polling [{polls}/{max_polls}] TaskID={task_id} Status={status}",
file=sys.stderr,
)
if status == TASK_STATUS_SUCCESS:
return result
if status == TASK_STATUS_FAILED:
failure = result.get("FailureReason", {})
raise RuntimeError(
f"Task failed: code={failure.get('Code')}, msg={failure.get('Msg')}"
)
raise TimeoutError(
f"Task {task_id} still running after {max_wait}s. "
f"Query manually: python scripts/music_generate.py query --task-id {task_id}"
)
def generate_song(
client: VolcEngineApiClient,
billing: str = "postpaid",
lyrics: Optional[str] = None,
prompt: Optional[str] = None,
model_version: str = "v4.3",
genre: Optional[str] = None,
mood: Optional[str] = None,
gender: Optional[str] = None,
timbre: Optional[str] = None,
duration: Optional[int] = None,
key: Optional[str] = None,
kmode: Optional[str] = None,
tempo: Optional[str] = None,
instrument: Optional[str] = None,
genre_extra: Optional[str] = None,
scene: Optional[str] = None,
lang: Optional[str] = None,
vod_format: Optional[str] = None,
max_wait: int = MAX_WAIT_SECONDS,
) -> dict:
if not lyrics and not prompt:
return {"status": "error", "error": "Either --lyrics or --prompt must be provided"}
body: Dict[str, Any] = {"ModelVersion": model_version}
if lyrics:
body["Lyrics"] = lyrics
if prompt:
body["Prompt"] = prompt
if genre:
body["Genre"] = genre
if mood:
body["Mood"] = mood
if gender:
body["Gender"] = gender
if timbre:
body["Timbre"] = timbre
if duration:
body["Duration"] = duration
if key:
body["Key"] = key
if kmode:
body["Kmode"] = kmode
if tempo:
body["Tempo"] = tempo
if instrument:
body["Instrument"] = instrument
if genre_extra:
body["GenreExtra"] = genre_extra
if scene:
body["Scene"] = scene
if lang:
body["Lang"] = lang
if vod_format:
body["VodFormat"] = vod_format
action = _get_song_action("song", billing)
resp = client.request(action, body)
task_id = resp.get("Result", {}).get("TaskID")
if not task_id:
return {"status": "error", "error": f"No TaskID returned: {resp}"}
print(f"Song task submitted: TaskID={task_id}", file=sys.stderr)
try:
result = _poll_task(client, task_id, max_wait)
except TimeoutError as e:
return {"status": "timeout", "mode": "song", "task_id": task_id, "error": str(e)}
detail = result.get("SongDetail", {})
return {
"status": "success",
"mode": "song",
"task_id": task_id,
"audio_url": detail.get("AudioUrl"),
"duration": detail.get("Duration"),
"lyrics": detail.get("Lyrics"),
"genre": detail.get("Genre"),
"mood": detail.get("Mood"),
"gender": detail.get("Gender"),
"error": None,
}
def generate_bgm(
client: VolcEngineApiClient,
text: str,
billing: str = "postpaid",
duration: Optional[int] = None,
version: str = "v5.0",
segments: Optional[str] = None,
enable_input_rewrite: bool = False,
max_wait: int = MAX_WAIT_SECONDS,
) -> dict:
if not text:
return {"status": "error", "error": "--text is required and cannot be empty"}
body: Dict[str, Any] = {
"Text": text,
"Version": version,
"EnableInputRewrite": enable_input_rewrite,
}
if duration:
body["Duration"] = duration
if segments:
try:
body["Segments"] = json.loads(segments)
except json.JSONDecodeError:
return {"status": "error", "error": f"Failed to parse segments JSON: {segments}"}
action = _get_song_action("bgm", billing)
resp = client.request(action, body)
task_id = resp.get("Result", {}).get("TaskID")
if not task_id:
return {"status": "error", "error": f"No TaskID returned: {resp}"}
print(f"BGM task submitted: TaskID={task_id}", file=sys.stderr)
try:
result = _poll_task(client, task_id, max_wait)
except TimeoutError as e:
return {"status": "timeout", "mode": "bgm", "task_id": task_id, "error": str(e)}
detail = result.get("SongDetail", {})
return {
"status": "success",
"mode": "bgm",
"task_id": task_id,
"audio_url": detail.get("AudioUrl"),
"duration": detail.get("Duration"),
"prompt": detail.get("Prompt"),
"error": None,
}
def generate_lyrics(
client: VolcEngineApiClient,
prompt: str,
genre: Optional[str] = None,
mood: Optional[str] = None,
gender: Optional[str] = None,
model_version: Optional[str] = None,
) -> dict:
if not prompt:
return {"status": "error", "error": "--prompt is required and cannot be empty"}
body: Dict[str, Any] = {"Prompt": prompt}
if genre:
body["Genre"] = genre
if mood:
body["Mood"] = mood
if gender:
body["Gender"] = gender
if model_version:
body["ModelVersion"] = model_version
resp = client.request("GenLyrics", body)
result = resp.get("Result", {})
return {
"status": "success",
"mode": "lyrics",
"task_id": result.get("TaskID"),
"lyrics": result.get("Lyrics"),
"genre": result.get("Genre"),
"mood": result.get("Mood"),
"gender": result.get("Gender"),
"error": None,
}
def query_task(client: VolcEngineApiClient, task_id: str) -> dict:
resp = client.request("QuerySong", {"TaskID": task_id})
result = resp.get("Result", {})
status = result.get("Status")
detail = result.get("SongDetail", {})
failure = result.get("FailureReason")
status_map = {0: "waiting", 1: "processing", 2: "success", 3: "failed"}
return {
"status": status_map.get(status, f"unknown({status})"),
"mode": "query",
"task_id": task_id,
"audio_url": detail.get("AudioUrl"),
"duration": detail.get("Duration"),
"lyrics": detail.get("Lyrics"),
"genre": detail.get("Genre"),
"mood": detail.get("Mood"),
"failure_reason": failure,
"error": None,
}
def main():
parser = argparse.ArgumentParser(
description="Music generation using Volcengine Imagination API"
)
subparsers = parser.add_subparsers(dest="mode", required=True)
# --- song ---
song_parser = subparsers.add_parser("song", help="Generate vocal song")
song_parser.add_argument("--lyrics", help="Lyrics with structure tags")
song_parser.add_argument("--prompt", help="Text prompt (Chinese, 5-700 chars)")
song_parser.add_argument(
"--model-version", default="v4.3", choices=["v4.0", "v4.3"]
)
song_parser.add_argument("--genre", help="Music genre")
song_parser.add_argument("--mood", help="Music mood")
song_parser.add_argument("--gender", choices=["Female", "Male"])
song_parser.add_argument("--timbre", help="Vocal timbre")
song_parser.add_argument("--duration", type=int, help="Duration in seconds [30-240]")
song_parser.add_argument("--key", help="Musical key (v4.3)")
song_parser.add_argument("--kmode", choices=["Major", "Minor"], help="Key mode (v4.3)")
song_parser.add_argument("--tempo", help="Tempo (v4.3)")
song_parser.add_argument("--instrument", help="Instruments, comma-separated (v4.3)")
song_parser.add_argument("--genre-extra", help="Secondary genres, comma-separated, max 2 (v4.3)")
song_parser.add_argument("--scene", help="Scene tags, comma-separated (v4.3)")
song_parser.add_argument("--lang", choices=["Chinese", "English", "Instrumental/Non-vocal"])
song_parser.add_argument("--vod-format", choices=["wav", "mp3"])
song_parser.add_argument(
"--billing", default="postpaid", choices=["prepaid", "postpaid"]
)
song_parser.add_argument(
"--timeout", type=int, default=MAX_WAIT_SECONDS, help="Max wait seconds"
)
# --- bgm ---
bgm_parser = subparsers.add_parser("bgm", help="Generate instrumental BGM")
bgm_parser.add_argument("--text", required=True, help="BGM description")
bgm_parser.add_argument("--duration", type=int, help="Duration in seconds [30-120]")
bgm_parser.add_argument("--version", default="v5.0", help="Model version")
bgm_parser.add_argument(
"--segments",
help='JSON array of segments, e.g. \'[{"Name":"verse","Duration":20}]\'',
)
bgm_parser.add_argument("--enable-input-rewrite", action="store_true")
bgm_parser.add_argument(
"--billing", default="postpaid", choices=["prepaid", "postpaid"]
)
bgm_parser.add_argument(
"--timeout", type=int, default=MAX_WAIT_SECONDS, help="Max wait seconds"
)
# --- lyrics ---
lyrics_parser = subparsers.add_parser("lyrics", help="Generate lyrics")
lyrics_parser.add_argument("--prompt", required=True, help="Lyrics prompt (Chinese)")
lyrics_parser.add_argument("--genre", help="Music genre")
lyrics_parser.add_argument("--mood", help="Music mood")
lyrics_parser.add_argument("--gender", choices=["Female", "Male"])
lyrics_parser.add_argument("--model-version", default=None)
# --- query ---
query_parser = subparsers.add_parser("query", help="Query task status")
query_parser.add_argument("--task-id", required=True, help="Task ID to query")
args = parser.parse_args()
try:
client = _get_client()
except PermissionError as e:
print(
json.dumps({"status": "error", "error": str(e)}, indent=2, ensure_ascii=False)
)
sys.exit(1)
try:
if args.mode == "song":
result = generate_song(
client,
billing=args.billing,
lyrics=args.lyrics,
prompt=args.prompt,
model_version=args.model_version,
genre=args.genre,
mood=args.mood,
gender=args.gender,
timbre=args.timbre,
duration=args.duration,
key=args.key,
kmode=args.kmode,
tempo=args.tempo,
instrument=args.instrument,
genre_extra=args.genre_extra,
scene=args.scene,
lang=args.lang,
vod_format=args.vod_format,
max_wait=args.timeout,
)
elif args.mode == "bgm":
result = generate_bgm(
client,
text=args.text,
billing=args.billing,
duration=args.duration,
version=args.version,
segments=args.segments,
enable_input_rewrite=args.enable_input_rewrite,
max_wait=args.timeout,
)
elif args.mode == "lyrics":
result = generate_lyrics(
client,
prompt=args.prompt,
genre=args.genre,
mood=args.mood,
gender=args.gender,
model_version=args.model_version,
)
elif args.mode == "query":
result = query_task(client, args.task_id)
else:
result = {"status": "error", "error": f"Unknown mode: {args.mode}"}
except Exception as e:
result = {"status": "error", "error": str(e)}
print(json.dumps(result, indent=2, ensure_ascii=False))
sys.exit(0 if result.get("status") in ("success",) else 1)
if __name__ == "__main__":
main()
音乐生成技能
使用火山引擎音乐生成 API 生成音乐,支持人声歌曲、纯音乐 BGM 和 AI 歌词生成。
触发条件
1. 用户想生成歌曲(通过歌词或文本描述) 2. 用户需要背景音乐、纯音乐或配乐 3. 用户想要 AI 生成歌词 4. 用户提到"写歌"、"音乐生成"、"BGM"、"背景音乐"、"歌词"
环境变量
支持两种鉴权方式(网关优先):
方案一:API 网关(推荐)
ARK_SKILL_API_BASE— API 网关基础地址ARK_SKILL_API_KEY— API 网关鉴权密钥
方案二:直连 AK/SK
VOLCENGINE_ACCESS_KEY— AccessKey IDVOLCENGINE_SECRET_KEY— AccessKey Secret- 获取方式:火山引擎控制台 → 账号(右上角)→ 密钥管理 → 新建密钥
使用流程
1. 判断用户意图,选择模式(song / bgm / lyrics)。 2. cd 到技能目录:skills/byted-music-generate。 3. 运行脚本。脚本会自动轮询 API,可能需要数分钟才能完成(song/bgm 通常需要 1–5 分钟)。 4. 监控执行:如果运行环境将命令转入后台,你必须每隔 10 秒读取终端输出,检查脚本是否完成。脚本会将轮询进度输出到 stderr,完成时输出一行 JSON 到 stdout。 5. 完成后,将 JSON 中的 audio_url 或 lyrics 返回给用户。
三种模式
1. song — 人声歌曲
用户提供歌词(Lyrics)或文本描述(Prompt)来生成人声歌曲。
# 通过文本描述
python scripts/music_generate.py song --prompt "一首关于夏天海边的歌" --genre Pop --gender Female
# 通过歌词
python scripts/music_generate.py song --lyrics "[verse]\n月光洒在窗台\n回忆像水一样流淌\n[chorus]\n你是我的月光" --genre Folk --mood "Sentimental/Melancholic/Lonely"注意:--lyrics 和 --prompt 互斥,歌词优先。如果用户没有提供歌词,可以先用 lyrics 模式生成歌词,再传给 song 模式。
2. bgm — 纯音乐 BGM
用自然语言描述想要的音乐。v5.0 模型不需要 Genre/Mood 参数,在 --text 中描述即可。
python scripts/music_generate.py bgm --text "轻松的咖啡厅氛围音乐,带有钢琴和吉他" --duration 60
# 带曲式结构片段
python scripts/music_generate.py bgm --text "史诗感的游戏配乐" --segments '[{"Name":"intro","Duration":10},{"Name":"chorus","Duration":30}]'3. lyrics — 歌词生成
同步返回(无需轮询)。可单独使用,也可作为 song 模式的前置步骤。
python scripts/music_generate.py lyrics --prompt "一首关于毕业离别的歌" --genre Folk --mood "Sentimental/Melancholic/Lonely" --gender Female手动查询任务(超时兜底)
python scripts/music_generate.py query --task-id "202601397834584670076931"模式判断逻辑
用户请求
↓
包含"纯音乐/BGM/背景音乐/配乐"?
├─ 是 → bgm 模式
└─ 否 → 包含"歌词/写歌词"且不要求音频?
├─ 是 → lyrics 模式
└─ 否 → song 模式
├─ 用户提供了歌词 → --lyrics
└─ 用户只描述了主题 → --prompt(或先生成歌词再生成歌曲)脚本参数
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(后付费,默认) |
--timeout | 否 | 最大等待秒数(默认 300) |
bgm 模式
| 参数 | 必填 | 说明 |
|---|---|---|
--text | 是 | 自然语言描述 |
--duration | 否 | 时长(秒)[30-120] |
--segments | 否 | 曲式结构片段 JSON 数组 |
--version | 否 | 模型版本(默认 v5.0) |
--enable-input-rewrite | 否 | 启用提示词改写 |
--billing | 否 | prepaid(预付费)/ 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和手动查询命令提供给用户。 - 若版权检查失败(code 50000001):建议用户丰富描述或增加音频时长后重试。
参考资料
- 可用参数值(流派/情绪/音色/乐器等):references/parameters.md
- 火山引擎音乐生成文档
- API 签名指南
Related skills
FAQ
What API does byted-music-generate use?
It uses the Volcengine Music Generation API and supports vocal songs, instrumental BGM, and AI lyrics generation.
How long does a generation take?
The script polls the API internally and typically takes 1 to 5 minutes for song or bgm modes.