# # 公共字段 1.**请求Host:** **https://open.volcengineapi.com** 2.**请求Header** > 描述：http请求中header需增加的字段 |参数名 |参数类型 |是否必填 |描述 | |---|---|---|---| |Host |String |是 |[open.volcengineapi.com](http://open.volcengineapi.com) | |X\-Date |String |是 |使用UTC时间，精确到秒。请使用格式：YYYYMMDD'T'HHMMSS'Z' ，例如：20201103T104027Z | |Authorization |String |是 |HMAC\-SHA256 Credential={AccessKeyId}/{ShortDate}/{Region}/{Service}/request, SignedHeaders={SignedHeaders}, Signature={Signature}|\ | | | |签名完整过程详见：[签名示例](https://www.volcengine.com/docs/6369/67269) | |Content\-Type |String |是 |MIME类型，固定值： application/json | |X\-Content\-Sha256 |String |否 |对完整请求Body的加密结果，HexEncode(Hash(RequestPayload))HexEncodeHexEncode代指转16进制编码|\ | | | |Hash代指SHA256算法|\ | | | |RequestPayload代指完整的请求的body。 | **Authorization中的信息含义：** |名称 |类型 |备注 | |---|---|---| |AccessKeyId |String |请求的AccessKey。|\ | | | |\ | | |AK/SK获取说明，参考：https://www.volcengine.com/docs/84992/1404668|\ | | |说明：在调用火山引擎音乐openapi的各个能力之前，确保您已生成访问密钥（AccessKey）。AccessKey包括AccessKeyID（AK）和AccessKeySecret（SK），其中AccessKeyID用于标识用户，AccessKeySecret是用来验证用户的密钥，请妥善保管。|\ | | |获取方式：点击右上角账号，下拉列表选择【密钥管理】，点击【新建密钥】按钮，可获取AK/SK，可以此为凭证调用上述已接入应用的接口。注：安全起见，建议新建子账户，并使用子账户的AK/SK | |ShortDate |String |请求的短时间，使用UTC时间，精确到日。请使用格式：YYYYMMDD，例如：20221101 | |Region |String |请求的地域，固定值： cn\-beijing | |Service |String |请求的服务，固定值：imagination | |SignedHeaders |String |参与签名的Header，用分号分隔。 | |Signature |String |计算完毕的签名。 | # HTTP接口详情 ## 1.**GenLyrics** 描述：生成歌词 Method: POST 请求参数： |参数 |类型 |**参数位置** |是否必填 |描述 | |---|---|---|---|---| |Action |String |Query |是 |GenLyrics | |Version |String |Query |是 |"2024\-08\-12" | |Prompt |String |Body |是 |歌词提示词内容，仅支持中文，小于500个字符。 | |Genre |String |Body |否 |生成歌词的曲风，不传默认走预测，可选: ["Folk", "Pop", "Rock", "Chinese Style", "Hip Hop/Rap", "R&B/Soul", "Punk", "Electronic", "Jazz", "Reggae", "DJ"] | |Mood |String |Body |否 |生成歌词的风格，不传默认走预测，可选: ['Happy', 'Dynamic/Energetic', 'Sentimental/Melancholic/Lonely', 'Inspirational/Hopeful', 'Nostalgic/Memory', 'Excited', 'Sorrow/Sad', 'Chill', 'Romantic'] | |Gender |String |Body |否 |生成歌词的性别，不传默认走预测，可选值：["Female", "Male"] | |ModelVersion |String |Body |否 |生成歌词使用版本，需要输入参数: ["v4.0"] | 请求URL：https://open.volcengineapi.com?Action=GenLyrics&Version=2024\-08\-12 请求Body参数示例 ```JSON { "Prompt": "关于星空的歌", "Genre": "R&B/Soul", "Mood": "Dynamic/Energetic", "Gender": "Male" "ModelVersion": "v4.0" } ``` 返回参数 ```JSON { "Code": 0, "Message": "success", "Result": { "TaskID": "202408308524910527xxxxxx", // 任务ID "Lyrics": "xxxx", // 歌词 "Genre": "R&B/Soul", "Mood": "Dynamic/Energetic", "Gender": "Male" }, "ResponseMetadata": { "RequestId": "02172492414155226050340cd5020003c070b82113f9c524bc84a", "Action": "GenLyrics", "Version": "2024-08-12", "Service": "imagination", "Region": "cn-beijing", "Error": null } } ``` ## 2.**GenSongV4** 描述：创建生成歌曲任务(使用生成人声歌曲standard服务，请使用该接口) Method: POST 请求参数： |参数 |类型 |**参数位置** |是否必填 |描述 | |---|---|---|---|---| |Action |String |Query |是 |GenSongV4 | |Version |String |Query |是 |"2024\-08\-12" | |Lyrics |String |Body |否 |歌词内容，仅支持中文，5到700个字符。支持通过歌词精准生成，与Prompt二选一，优先级高于Prompt | |Prompt |String |Body |否 |提示词内容，仅支持中文，5到700个字符。支持通过提示词生成歌曲，与Lyrics二选一 | |Genre |String |Body |否 |生成歌曲的曲风，如果不传或者传入空字符串，服务会基于text内容提取或预测genre,可选: ["Folk", "Pop", "Rock", "Chinese Style", "Hip Hop/Rap", "R&B/Soul", "Punk", "Electronic", "Jazz", "Reggae", "DJ", "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"] | |Mood |String |Body |否 |生成歌曲的风格，如果不传或者传入空字符串，服务会基于text内容提取或预测mood,可选: ['Happy', 'Dynamic/Energetic', 'Sentimental/Melancholic/Lonely', 'Inspirational/Hopeful', 'Nostalgic/Memory', 'Excited', 'Sorrow/Sad', 'Chill', 'Romantic', 'Miss', 'Groovy/Funky', 'Dreamy/Ethereal', 'Calm/Relaxing'] | |Gender |String |Body |否 |生成歌曲的Gender，如果不传或者传入空字符串，服务会基于text内容提取或预测gender；可选值：["Female", "Male"] | |Timbre |String |Body |否 |生成歌曲的音色，如果不传或者传入空字符串，服务会基于text内容提取或预测timbre；可选:["Warm", "Bright", "Husky", "Electrified voice", "Sweet_AUDIO_TIMBRE", "Cute_AUDIO_TIMBRE", "Loud and sonorous", "Powerful", "Sexy/Lazy"] | |Duration |Int |Body |否 |生成指定音频时长，单位：s，生效范围[30，240] | |CallbackURL |String |Body |否 |配置回调地址后，会在任务完成后，通过http请求回调该地址，回调内容为json格式 | |SkipCopyCheck |Bool |Body |否 |选填歌词版权检测开关 | |TosBucket |String |Body |否 |选填用户自定义tos存储桶名称 | 请求URL：https://open.volcengineapi.com?Action=GenSongV4&Version=2024\-08\-12 请求Body参数示例 ```JSON { "Prompt": "关于星空的歌", "Genre": "R&B/Soul", "Mood": "Dynamic/Energetic", "Gender": "Male", "Timbre": "Warm", "Duration": 60, "CallbackURL": "" } ``` 返回示例 ```JSON { "Code": 0, "Message": "success", "Result": { "TaskID": "202408308513817850019840", // 任务ID "PredictedWaitTime": 0 // 预计等待时间（单位秒） }, "ResponseMetadata": { "RequestId": "02172491885215426050340cd5020003c070b82113f9c52acdbc4", "Action": "GenSong", "Version": "2024-08-12", "Service": "imagination", "Region": "cn-beijing", "Error": null } } ``` ## 3.**QuerySong** 描述：通过任务ID查询生成歌曲信息 Method: POST 请求参数 |参数 |类型 |**参数位置** |是否必填 |描述 | |---|---|---|---|---| |Action |String |Query |是 |QuerySong | |Version |String |Query |是 |"2024\-08\-12" | |TaskID |String |Body |是 |任务ID | 请求URL：https://open.volcengineapi.com?Action=QuerySong&Version=2024\-08\-12 请求Body参数示例 ```JSON { "TaskID": "202408308513817850019840" } ``` 返回示例 **注1：接口默认不提供歌词文件，如需要歌词时间戳可以通过解析“歌词字幕”实现** **注2：默认提供wav音频文件（因视频云链路有默认转码逻辑，可能出现mp4等格式情况），url有效期为1年，您需要拿到url后自行做转存并转化成您预期的音频格式** ```JSON { "Code": 0, "Message": "success", "Result": { "TaskID": "202408308513817850019840", "Status": 3, // 任务状态 0->等待中, 1->处理中, 2->成功, 3->失败 "Progress": 100, // 生成进度 "FailureReason": { // 任务失败原因，任务执行成功时为null "Code": 300061, "Msg": "InputLyricsPlagiarized" }, "SongDetail": { "AudioUrl": "xxxxx", // 音频地址 URL域名规则：v{1-50}-default.douyinvod.com "Captions": "{}", // 歌词字幕 "Lyrics": "xxxxxxx", // 生成歌曲所使用的歌词 "Duration": 46.0024375 // 音频时长，单位秒 "Genre":"",//曲风 "Mood":"",//情绪 "Gender":"",//性别 "TosPath":"",//用户自定义tos保存路径 "CallbackURL":"",//回调地址 "Timbre":"",//音色 "Prompt":""//提示词 } }, "ResponseMetadata": { "RequestId": "02172492501059326050340cd5020003c070b82113f9c52a42fa4", "Action": "QuerySong", "Version": "2024-08-12", "Service": "imagination", "Region": "cn-beijing", "Error": null } } ``` ## 4.QueryUsage 描述：用量查询 Method: GET 请求参数 |参数 |类型 |**参数位置** |是否必填 |描述 | |---|---|---|---|---| |Action |String |Query |是 | QueryUsage | |Version |String |Query |是 |"2024\-08\-12" | 请求URL：https://open.volcengineapi.com?Action=QueryUsage&Version=2024\-08\-12 返回参数 ```JSON { "Code": 0, "Message": "Success", "Result": { "Data": [ { "Stauts": 1, // 授权状态 1-正式，2-试用 "StartTime": 1726738015, // 授权开始时间 "EndTime": 1758274015, // 授权结束时间 "MusicQuota": 10000, // 音乐额度 "MusicUsed": 26, // 音乐用量 "LyricsQuota": 50000, // 歌词额度 "LyricsUsed": 26, // 歌词用量 "ProductName": "BigMusic" // 产品名称 } ] }, "ResponseMetadata": { "RequestId": "202411251458209246F74FE96835873BE2", "Action": "QueryUsage", "Version": "2024-08-12", "Service": "imagination", "Region": "cn-beijing", "Error": null } } ``` # 歌词格式说明在提交生成歌曲任务时，若是通过传递Lyrics参数生成，此时可以通过标签控制歌词结构。一个完整的歌词结构说明: **前奏:** intro，歌曲开始的音乐部分，主要用于引导歌曲的整体氛围。 **主歌:** verse，通常在前奏之后，歌曲中叙述歌曲故事或主题的部分。 **副歌:** chorus，一般在主歌之后，旋律有记忆点和感染力，是整首歌的高潮，进一步强化歌曲的主题和情感。 **间奏:** inst，歌曲中的纯音乐段落，用于连接不同的演唱部分。 **尾奏:** outro，歌曲结束后的音乐段落，用于营造歌曲结束的氛围。 **桥段:** bridge，通常出现在歌曲中段或接近结尾处，是一个过渡部分，用于连接不同的歌曲段落。例如: ```Plain Text [intro] [verse] 记得那一天那一天我们相恋说好彼此都不说再见遵守诺言用心去相恋我为你撑伞你为我取暖 [inst] [chorus] 当我把心交给你的那一天你却消失在我的眼前事到如今已经过了好多年是否你还像从前 [outro] ``` # 可选参数说明 ## Genre |

选项

|

中文说明

|\ |---|---| | | | |

Folk

|

民谣

|\ | | | |

Pop

|

流行

|\ | | | |

Rock

|

摇滚

|\ | | | |

Chinese Style

|

国风

|\ | | | |

Hip Hop/Rap

|

嘻哈

|\ | | | |

R&B/Soul

|

R&B

|\ | | | |

Punk

|

朋克

|\ | | | |

Electronic

|

电子

|\ | | | |

Jazz

|

爵士

|\ | | | |

Reggae

|

雷鬼

|\ | | | |

DJ

|

DJ

|\ | | | |

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

|

当代节奏布鲁斯

|\ | | | ## Mood |

选项

|

中文说明

|\ |---|---| | | | |

Happy

|

快乐

|\ | | | |

Dynamic/Energetic

|

活力

|\ | | | |

Sentimental/Melancholic/Lonely

|

EMO

|\ | | | |

Inspirational/Hopeful

|

鼓舞

|\ | | | |

Nostalgic/Memory

|

怀旧

|\ | | | |

Excited

|

兴奋

|\ | | | |

Sorrow/Sad

|

伤感

|\ | | | |

Chill

|

放松

|\ | | | |

Romantic

|

浪漫

|\ | | | |

Miss

|

思念

|\ | | | |

Groovy/Funky

|

律动

|\ | | | |

Dreamy/Ethereal

|

梦幻

|\ | | | |

Calm/Relaxing

|

平静

|\ | | | ## Timbre |

选项

|

中文说明

|\ |---|---| | | | |

Warm

|

温暖

|\ | | | |

Bright

|

明亮

|\ | | | |

Husky

|

烟嗓

|\ | | | |

Electrified voice

|

电音

|\ | | | |

Sweet_AUDIO_TIMBRE

|

甜美

|\ | | | |

Cute_AUDIO_TIMBRE

|

可爱

|\ | | | |

Loud and sonorous

|

浑厚

|\ | | | |

Powerful

|

高亢

|\ | | | |

Sexy/Lazy

|

慵懒

|\ | | | # 异步回调说明对于生成歌曲创建的任务，在任务执行完成时，我们会根据传入的异步回调地址CallbackURL，通过POST请求的形式将任务执行结果通知到用户系统。 ## 1、异步回调请求参数 ```JSON { "CallbackTime": 1724984476, // 回调时间，单位s "TaskID": "202408308513817850019840", // 任务ID "Status": 3, // 任务状态 2->成功, 3->失败 "FailureReason": { // 任务失败原因，任务执行成功时为null "Code": 100001, "Msg": "" }, "SongDetail": { "AudioUrl": "xxxxx", // 音频地址 URL域名规则：v{1-50}-default.douyinvod.com "Captions": "{}", // 歌词字幕 "Lyrics": "xxxxxxx", // 生成歌曲所使用的歌词 "Duration": 46.0024375 // 音频时长，单位秒 "Genre":"",//曲风 "Mood":"",//情绪 "Gender":"",//性别 "TosPath":"",//用户自定义tos保存路径 "CallbackURL":"",//回调地址 "Timbre":"",//音色 "Prompt":""//提示词 } } ``` ## 2、异步回调特性 1. 在异步回调请求交互时，如果我们收到的应答不是success，我们会认为通知失败，会通过一定策略定期重新发起通知。通知的间隔频率为：5m、10m。 2. 回调请求用POST方式发送通知信息，数据格式为json。 # 签名源码示例暂时没有SDK，需要自行计算签名，请参考：[签名源码示例--API签名调用指南-火山引擎](https://www.volcengine.com/docs/6369/185600) java请使用我们提供的demo： Python请使用我们提供的参考demo：

音视频理解与处理