# Riffusion API 调用说明文档

## Riffusion API 调用说明文档

### 概述

Riffusion API 是一套音乐生成服务接口，可以通过提供歌词、主题或现有音频来创作音乐作品。本文档将指导您如何正确调用这些接口，理解它们之间的逻辑关系，并充分利用各种创作模式。

### 基本工作流程

Riffusion API 的标准工作流程通常包含以下步骤：

1. **生成音乐任务**：通过专业模式或灵感模式提交创作请求

2. **获取生成结果**：使用返回的任务ID查询生成状态和结果

3. **高级创作**：可选择上传音频并使用各种变形模式进行二次创作

### 授权认证

所有接口调用都需要在请求头中包含授权信息：

```
Authorization: Bearer your-key
```

### 主要接口使用说明

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

您可以选择两种方式生成音乐：

**专业模式**（`/riffusion/generate`）：提供详细歌词、标签和标题，适合有明确创作意图的用户

**灵感模式**（`/riffusion/generate/topic`）：仅提供主题词，系统自动生成歌词和音乐，适合寻找创作灵感的用户

这两种模式都会返回两个任务ID，每个ID对应一个独立的音乐创作作品。系统会基于相同输入生成两个不同版本，供用户选择。

#### 2. 查询生成结果

提交生成请求后，使用返回的任务ID调用`/riffusion/feed/{riff_id1},{riff_id2}`接口查询结果。需要注意：

处理状态通过`status`字段判断：`process`（处理中）或`success`（成功）

处理进度通过`process`字段获取（0-100）

音频是否生成成功通过`generations[].audio_url`是否有值来判断

完成的音乐作品可通过`audio_url`直接获取

建议实现定时轮询查询结果，直到状态变为`success`。

#### 3. 音频上传与二次创作

Riffusion支持上传现有音频并进行二次创作，通过以下流程实现：

1. 调用`/riffusion/upload`接口上传音频文件（URL形式）

2. 获取返回的`id`作为`audio_upload_id`

3. 选择下列某种变形模式进行二次创作

#### 4. 变形模式说明

Riffusion提供多种音乐变形模式，需在`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 API的创作潜力，生成丰富多样的音乐作品。