Riffusion API 调用说明文档

Riffusion API 调用说明文档

概述

Riffusion 接口提供音乐生成能力：既可以给出歌词或主题来创作，也可以基于已有音频继续加工。本文说明各接口的调用方式、它们之间的关系，以及各种创作模式该怎么用。

基本工作流程

标准流程通常是：

1. 生成音乐任务：用专业模式或灵感模式发出创作请求
2. 获取生成结果：拿返回的任务 ID 查询状态与结果
3. 高级创作：可选——上传音频后用变形模式做二次创作

授权认证

所有接口都需要在请求头带上授权信息：

Authorization: Bearer <令牌>

请求统一发往 https://api.allyang.cn。

主要接口使用说明

1. 音乐生成（两种模式）

生成音乐有两条路：

• 专业模式（/riffusion/generate）：由你提供歌词、标签与标题，适合创作意图明确的场景
• 灵感模式（/riffusion/generate/topic）：只给主题词，歌词与旋律交给系统，适合先找灵感

两条路都会返回两个任务 ID，各自对应一个作品——同一输入会产出两个版本供挑选。

2. 查询生成结果

提交之后，用返回的任务 ID 请求 /riffusion/feed/{riff_id1},{riff_id2} 取结果。判断要点：

• 处理状态看 status：process 表示处理中，success 表示完成
• 处理进度看 process 字段（0-100）
• 音频是否可用，看 generations[].audio_url 是否有值
• 完成后的作品可直接从 audio_url 取得

建议做定时轮询，直到 status 变为 success。

3. 音频上传与二次创作

也支持上传已有音频再创作，步骤如下：

1. 调用 /riffusion/upload 上传音频（以 URL 形式）
2. 取返回的 id，作为 audio_upload_id
3. 选择下面任一变形模式继续加工

4. 变形模式说明

变形模式在 morph 对象的 transform 参数中指定：

• **翻唱(cover)**：沿用原曲风格，换掉歌词与人声
• **续写(extend)**：顺着原曲往后写，需指定 crop_end_at
• **替换(inpaint)**：改掉原曲的某个片段，需指定 replace_start_at 与 replace_end_at
• **人声替换(swap_vocals)**：只动人声，伴奏保留
• **音乐风格替换(swap_sound)**：只动伴奏，人声保留

每种模式的源素材，既可以是系统生成的作品 ID（riff_id），也可以是你上传的音频 ID（audio_upload_id）。

参数调整与创意控制

通过 morph 对象中的参数可以细调效果：

• normalized_lyrics_strength：歌词的左右程度（0-1）
• normalized_sound_prompt_strength：声音提示的左右程度（0-1）
• normalized_weirdness：创意的怪异程度（0-1）
• normalized_cover_strength：翻唱时对原曲的忠实程度（0-1）
• normalized_variation_strength：变异程度（0-1）

取值越大该特性越强，越小则越弱。

典型使用场景

1. 创作原创歌曲：专业模式给完整歌词，或灵感模式给一个主题
2. 歌曲改编：上传已有歌曲，用 cover 模式换风格或换语言
3. 混合创作：上传片段后用 extend 续写，或用 inpaint 改掉其中一段
4. 保留原曲风格换歌词：用 swap_vocals
5. 保留原曲歌词换风格：用 swap_sound

最佳实践

1. 歌词带上结构标记（[Verse]、[Chorus] 等）效果更好
2. 查询结果时做指数退避，别把轮询打得太密
3. 复杂创作可以先用灵感模式出草稿，再用专业模式细修
4. 调 normalized 系列参数时小步走，看效果再决定下一步
5. 把生成的音乐 ID 存好，后续各种变形模式都用得上

弄清这些接口的调用关系之后，就能把 Riffusion 的创作能力用起来，产出多样的音乐作品。