申请流程
要使用 API，需要先到 Riffusion Audios Generation API 对应页面申请对应的服务，进入页面之后，点击「Acquire」按钮，如图所示：
如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。
在首次申请时会有免费额度赠送，可以免费使用该 API。
基本使用
想些什么歌曲，可以任意输入一段文字，比如我想生成一个关于圣诞的歌曲，就可以输入 a song for Christmas，如图所示：
可以看到这里我们设置了 Request Headers，包括：
accept：想要接收怎样格式的响应结果，这里填写为application/json，即 JSON 格式。authorization：调用 API 的密钥，申请之后可以直接下拉选择。
另外 Request Body 的参数包括：
action：此次音乐生成任务的行为，生成歌曲是generate。model：创建歌曲采用的模型，目前主要有：FUZZ-1.0、FUZZ-1.1、FUZZ-1.0 Pro、FUZZ-1.1 Pro。lyric：歌曲的歌词内容。custom：是否采用自定义方式生成歌曲。prompt：灵感模式下的提示词。style：歌曲风格参数。title：歌曲标题信息。callback_url：需要回调结果的 URL。instrumental：是否为无歌词模式。
如上参数和官方的自定义生成的映射关系如下：
model：对应 Riffusion 账号设置页面的模型选择，如下图所示lyric：对应 Rifussion 自定义生成页面的「Lyrics」部分，如下图所示style：对应 Rifussion 自定义生成页面的「Sound」部分，实际上是指定一些风格，如下图所示title：对应 Rifussion 自定义生成页面的「Details」部分，用于指定歌曲标题，如下图所示instrumental：对应 Rifussion 自定义生成页面的「Instrumental」开关，用于设置无歌词模式，如下图所示
选择之后，可以发现右侧也生成了对应代码，如图所示：
点击「Try」按钮即可进行测试，如上图所示，这里我们就得到了如下结果：
1 |
{ |
返回结果一共有多个字段，介绍如下：
success，此时音乐生成任务的状态情况。data，此次音乐任务的结果 -id，此时音乐生成任务的 ID。prompt，此时音乐生成任务的提示词。audio_url，此时音乐生成任务的音频链接。image_url，此时音乐生成任务的封面链接。state，此时音乐生成任务的状态。duration，此时音乐的时长信息。style，此时音乐的风格信息。model，此时音乐生成任务采用的模型信息。lyric，此时音乐生成任务的歌词信息。
可以看到我们得到了想生成的音乐信息，我们只需要根据结果中 data 的音乐链接地址获取生成的 Riffusion 音乐即可。
另外如果想生成对应的对接代码，可以直接复制生成，例如 CURL 的代码如下：
1 |
curl -X POST 'https://api.acedata.cloud/riffusion/audios' \ |
自定义生成
如果想自定义生成歌词，可以输入歌词：
这时候 lyric 字段可以传入类似如下内容：
1 |
[Verse]Woke up with the sun in my eyesNo clouds above just blue in the skiesShoes on my feet I’m ready to runEvery step feels like a loaded gun[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high[Verse 2]Dancing through the city streetsA rhythm pounding in my heartbeatStrangers smile it’s catching onThis world’s a stage we’re all a song[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high[Bridge]Throw your worries out the doorLet them sink to the ocean floorWe’re alive and it’s enoughLife is messy but it’s love[Chorus]Happy days are rolling inLet the joy beneath my skinNo more shadows no more liesJust the truth that lifts me high |
接下来我们要根据歌词、标题、风格自定义生成歌曲，就可以指定如下内容：
- lyric：歌词文本
- custom：填写为
true，代表自定义生成，该参数默认为 false，代表使用prompt生成。 - title：歌曲的标题。
- style：歌曲的风格，选填。
填写样例如下：
填写完毕之后自动生成了代码如下：
对应的代码：
1 |
curl -X POST 'https://api.acedata.cloud/riffusion/audios' \ |
测试允许，生成的效果是类似的。
1 |
{ |
翻唱歌曲
如果想对已经生成的歌曲进行翻唱操作的操作，可以输入上文生成的歌曲进行翻唱，接下来我们要根据歌词、标题、风格自定义生成歌曲，就可以指定如下内容：
- action：此次歌曲任务的行为，目前支持：generate、cover、extend、upload_cover、upload_extend、replace_section、swap_sound、swap_vocals，此次翻唱使用
cover参数。 - lyric：歌词文本
- title：歌曲的标题。
- audio_id：歌曲的ID。
- style：歌曲的风格，选填。
填写样例如下：
填写完毕之后自动生成了代码如下：
对应的代码：
1 |
curl -X POST 'https://api.acedata.cloud/riffusion/audios' \ |
测试允许，生成的效果是类似的。
1 |
{ |
续写歌曲
如果想续写歌曲的话，我们需要传入action参数值为：extend，接下来我们要根据歌词、标题、风格自定义生成歌曲，就可以指定如下内容：
- action：此次歌曲任务的行为，目前支持：generate、cover、extend、upload_cover、upload_extend、replace_section、swap_vocals、swap_sound，此次续写使用
extend参数。 - lyric：歌词文本
- title：歌曲的标题。
- audio_id：歌曲的ID。
- style：歌曲的风格，选填。
填写样例如下：
填写完毕之后自动生成了代码如下：
对应的代码：
1 |
curl -X POST 'https://api.acedata.cloud/riffusion/audios' \ |
测试允许，生成的效果是类似的。
1 |
{ |
替换片段
如果想对歌曲进行替换片段的话，我们需要传入action参数值为：replace_section，接下来我们要根据歌词、标题、风格自定义生成歌曲，就可以指定如下内容：
- action：此次歌曲任务的行为，目前支持：generate、cover、extend、upload_cover、upload_extend、replace_section、swap_vocals、swap_sound，此次续写使用
extend参数。 - lyric：需要替换后的歌词文本
- title：歌曲的标题。
- audio_id：歌曲的ID。
- style：歌曲的风格，选填。
填写样例如下：
填写完毕之后自动生成了代码如下：
对应的代码：
1 |
curl -X POST 'https://api.acedata.cloud/riffusion/audios' \ |
测试允许，生成的效果是类似的。
1 |
{ |
SwapSound生成
如果想使用官方的SwapSound操作，可以将action参数值设为：swap_sound，接下来我们要根据歌词、标题、风格自定义生成歌曲，就可以指定如下内容：
接下来我们要根据歌词、标题、风格自定义生成歌曲，就可以指定如下内容：
- action：此次歌曲任务的行为，目前支持：generate、cover、extend、upload_cover、upload_extend、swap_sound、swap_vocals。
- lyric：歌词文本
- title：歌曲的标题。
- audio_id：歌曲的ID。
- style：歌曲的风格，选填。
填写样例如下：
填写完毕之后自动生成了代码如下：
对应的代码：
1 |
curl -X POST 'https://api.acedata.cloud/riffusion/audios' \ |
测试允许，生成的效果是类似的。
1 |
{ |
SwapVocals 生成
如果想使用官方的SwapVocals操作，可以将action参数值设为：swap_vocals，接下来我们要根据歌词、标题、风格自定义生成歌曲，就可以指定如下内容：
- action：此次歌曲任务的行为，目前支持：generate、cover、extend、upload_cover、upload_extend、swap_sound、swap_vocals。
- lyric：歌词文本
- title：歌曲的标题。
- audio_id：歌曲的ID。
- style：歌曲的风格，选填。
填写样例如下：
填写完毕之后自动生成了代码如下：
对应的代码：
1 |
curl -X POST 'https://api.acedata.cloud/riffusion/audios' \ |
测试允许，生成的效果是类似的。
1 |
{ |
异步回调
由于 Riffusion Audios Generation API 生成的时间有时候会相对较长，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。
整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，生成任务的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。
下面我们通过示例来了解下具体怎样操作。
首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 https://webhook.site/，打开该网站即可得到一个 Webhook URL，如图所示：
将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/68368fc6-7f0a-425e-b63a-cc48631615fe。
接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入相应的参数，具体的内容如图所示：
点击运行，可以发现会立即得到一个结果，如下：
1 |
{ |
稍等片刻，我们可以在 https://webhook.site/68368fc6-7f0a-425e-b63a-cc48631615fe 上观察到生成任务的结果，如图所示：
内容如下：
1 |
{ |
可以看到结果中有一个 task_id 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。
错误处理
在调用 API 时，如果遇到错误，API 会返回相应的错误代码和信息。例如：
400 token_mismatched：Bad request, possibly due to missing or invalid parameters.400 api_not_implemented：Bad request, possibly due to missing or invalid parameters.401 invalid_token：Unauthorized, invalid or missing authorization token.429 too_many_requests：Too many requests, you have exceeded the rate limit.500 api_error：Internal server error, something went wrong on the server.
错误响应示例
1 |
{ |
结论
通过本文档，您已经了解了如何使用 Riffusion Audios Generation API 可通过输入提示词来生成音乐。希望本文档能帮助您更好地对接和使用该 API。如有任何问题，请随时联系我们的技术支持团队。
