# 公共字段 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. ## GenBGMForTime 描述：调用后付费接口创建生成纯音乐任务 Method: POST 请求参数： |参数 |类型 |**参数位置** |是否必填 |描述 | |---|---|---|---|---| |Action |String |Query |是 |GenBGMForTime | |Version |String |Query |是 |"2024\-08\-12" | |Text |String |Body |是 |必填，输入文本 | |Genre |list[string] |Body |否 |选填，曲风列表，最多可填入10个参数: ["corporate","dance/edm","orchestral","chill out","rock","hip hop","folk","funk","ambient","holiday","jazz","kids","world","travel","commercial","advertising","driving","cinematic","upbeat","epic","inspiring","business","video game","dark","pop","trailer","modern","electronic","documentary","soundtrack","fashion","acoustic","movie","tv","high tech","industrial","dance","video","vlog","marketing","game","radio","promotional","sports","party","summer","beauty"] | |Mood |list[string] |Body |否 |选填，情绪列表，最多可填入10个参数: ["positive","uplifting","energetic","happy","bright","optimistic","hopeful","cool","dreamy","fun","light","powerful","calm","confident","joyful","dramatic","peaceful","playful","soft","groovy","reflective","easy","relaxed","lively","smooth","romantic","intense","elegant","mellow","emotional","sentimental","cheerful happy","contemplative","soothing","proud","passionate","sweet","mystical","tranquil","cheerful","casual","beautiful","ethereal","melancholy","sad","aggressive","haunting","adventure","serene","sincere","funky","funny"] | |Instrument |list[string] |Body |否 |选填，乐器名称列表，最多可填入10个参数: |\ | | | | |["piano","drums","guitar","percussion","synth","electric guitar","acoustic guitar","bass guitar","brass","violin","cello","flute","organ","trumpet","ukulele","saxophone","double bass","harp","glockenspiel","synthesizer","keyboard","marimba","bass","banjo","strings"] | |Theme |list[string] |Body |否 |选填，生成音乐的主题列表，最多可填入10个参数: |\ | | | | |["inspirational","motivational","achievement","discovery","every day","love","technology","lifestyle","journey","meditation","drama","children","hope","fantasy","holiday","health","family","real estate","media","kids","science","education","progress","world","vacation","training","christmas","sales"] | |Duration |Int |Body |否 |选填，生成音乐的时长 (秒)，仅支持[1:60] | |TosBucket |Sting |Body |否 |选填，用户自定义火山tos桶名称。|\ | | | | |可参考[tos开通文档](https://www.volcengine.com/docs/84992/1521764)完成相关操作 | |CallbackURL |String |Body |否 |回调地址，可选。配置回调地址后，会在任务完成后，通过http请求回调该地址，回调内容为json格式 | **注意：入参简单的30s短音乐容易触发版权校验（错误码code:50000001），建议通过丰富text、增加参数数量、延长生成音乐时长等手段进行规避。** 请求URL：[https://open.volcengineapi.com?Action=GenBGMForTime&Version=2024-08-12](https://open.volcengineapi.com?Action=GenBGMForTime&Version=2024-08-12) 请求Body参数示例 ```JSON { "Text": "关于星空的背景纯音乐", "Mood": ["positive"], "Genre": ["corporate"] } ``` 返回示例 ```JSON { "Code": 0, "Message": "success", "Result": { "TaskID": "202408308513817850019840", // 任务ID }, "ResponseMetadata": { "RequestId": "02172491885215426050340cd5020003c070b82113f9c52acdbc4", "Action": "GenBGMForTime", "Version": "2024-08-12", "Service": "imagination", "Region": "cn-beijing", "Error": null } } ``` 2. ## **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" } ``` 返回示例 **注意：默认提供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 "Prompt": "xxxxxxx", // 生成纯音乐的提示词 "Duration": 46.0024375, // 音频时长，单位秒 "CallbackURL":"",//回调地址 "Theme":"",//主题 "Instrument":"",//乐器 "Mood":"", //情绪 "Genre":"", //曲风 "TosPath":"" //用户自定义的tos保存路径 } }, "ResponseMetadata": { "RequestId": "02172492501059326050340cd5020003c070b82113f9c52a42fa4", "Action": "QuerySong", "Version": "2024-08-12", "Service": "imagination", "Region": "cn-beijing", "Error": null } } ``` 3. ## 可选参数说明 ## Genre |

选项

|

中文说明

|\ |---|---| | | | |corporate |企业 | |dance/edm |舞蹈/电子舞曲 | |orchestral |管弦乐 | |chill out |轻松 | |rock |摇滚 | |hip hop |嘻哈 | |folk |民谣 | |funk |放克 | |ambient |氛围音乐 | |holiday |假期 | |jazz |爵士乐 | |kids |童乐 | |world |世界 | |travel |旅行 | |commercial |商业的 | |advertising |广告营销 | |driving |驾驶 | |cinematic |电影 | |upbeat |乐观的 | |epic |史诗 | |inspiring |鼓舞人心的 | |business |商业 | |video game |视频游戏 | |dark |黑暗的 | |pop |流行音乐 | |trailer |预告片 | |modern |现代的 | |electronic |电子的 | |documentary |记录 | |soundtrack |原声带 | |fashion |时尚 | |acoustic |自然声 | |movie |电影 | |tv |电视 | |high tech |高科技 | |industrial |工业的 | |dance |舞蹈 | |video |视频 | |vlog |视频博客 | |marketing |营销 | |game |游戏 | |radio |收音机 | |promotional |促销 | |sports |运动的 | |party |派对 | |summer |夏天 | |beauty |美丽 | ## Mood |

选项

|

中文说明

|\ |---|---| | | | |positive |积极的 | |uplifting |令人振奋的 | |energetic |精力充沛 | |happy |快乐 | |bright |明亮的 | |optimistic |乐观的 | |hopeful |充满希望的 | |cool |酷 | |dreamy |梦幻般的 | |fun |乐趣 | |light |轻音乐 | |powerful |强力的 | |calm |冷静的 | |confident |自信的 | |joyful |喜悦 | |dramatic |戏剧性 | |peaceful |平静的 | |playful |俏皮的 | |soft |轻柔 | |groovy |时髦的 | |reflective |反省性的 | |easy |简单的 | |relaxed |轻松 | |lively |活泼 | |smooth |平滑的 | |romantic |浪漫的 | |intense |激烈的 | |elegant |优雅的 | |mellow |醇厚 | |emotional |情绪化的 | |sentimental |多愁善感的 | |cheerful happy |开朗快乐 | |contemplative |沉思的 | |soothing |舒缓的 | |proud |自豪的 | |passionate |热情的 | |sweet |甜蜜 | |mystical |神秘 | |tranquil |宁静 | |cheerful |令人愉快的 | |casual |随意的 | |beautiful |美丽的 | |ethereal |空灵的 | |melancholy |忧郁的 | |sad |伤心 | |aggressive |挑衅的 | |haunting |令人难以忘怀的 | |adventure |冒险 | |serene |安详 | |sincere |真诚 | |funky |节奏强适宜跳舞的 | |funny |搞笑 | ## Theme |选项 |中文说明 | |---|---| |inspirational |灵感 | |motivational |激励 | |achievement |成就 | |discovery |发现 | |every day |日常 | |love |爱情 | |technology |科技 | |lifestyle |生活方式 | |journey |旅行 | |meditation |冥想 | |drama |戏剧 | |children |儿童 | |hope |希望 | |fantasy |幻想 | |holiday |假日 | |health |健康 | |family |家庭 | |real estate |房地产 | |media |媒体 | |kids |儿童 | |science |科学 | |education |教育 | |progress |进步 | |world |世界 | |vacation |度假 | |training |培训 | |christmas |圣诞 | |sales |销售 | ## Instrument |

选项

|

中文说明

|\ |---|---| | | | |piano |钢琴 | |drums |鼓 | |guitar |吉他 | |percussion |打击乐器 | |synth |合成器 | |electric guitar |电吉他 | |acoustic guitar |民谣吉他 | |bass guitar |低音吉他 | |brass |铜管乐器 | |violin |小提琴 | |cello |大提琴 | |flute |长笛 | |organ |风琴 | |trumpet |小号 | |ukulele |尤克里里 | |saxophone |萨克斯 | |double bass |低音提琴 | |harp |竖琴 | |glockenspiel |钟琴 | |synthesizer |（电子）合成器 | |keyboard |键盘乐器 | |marimba |马林巴琴 | |bass |贝斯 | |banjo |班卓琴 | |strings |弦乐器 | # 异步回调说明对于纯音乐创建的任务，在任务执行完成时，我们会根据传入的异步回调地址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 "Prompt": "xxxxxxx", // 生成纯音乐的提示词 "Duration": 46.0024375, // 音频时长，单位秒 "CallbackURL":"",//回调地址 "Theme":"",//主题 "Instrument":"",//乐器 "Mood":"", //情绪 "Genre":"", //曲风 "TosPath":"" //用户自定义的tos保存路径 } } ``` ## 2、异步回调特性 1. 在异步回调请求交互时，如果我们收到的应答不是success，我们会认为通知失败，会通过一定策略定期重新发起通知。通知的间隔频率为：5m、10m。 2. 回调请求用POST方式发送通知信息，数据格式为json。 # 签名源码示例暂时没有SDK，需要自行计算签名，请参考：[签名源码示例--API签名调用指南-火山引擎](https://www.volcengine.com/docs/6369/185600) java请使用我们提供的demo： Python请使用我们提供的参考demo：

音视频理解与处理