# Soundscape API 文档

## 1. 基础信息
- 主要 Base URL：`/api`
- 前端服务入口：`MusicApi`
- 产品标识：`soundscape`

## 2. 生成接口

### 2.1 标准生成
- 方法：POST
- 路径：`/audiogen`
- Content-Type：`application/json`
- 关键字段：
  - `descriptions` array<string>（前端将单条 prompt 包装为数组）
  - `duration` number
  - `cfg_coef` number
- 自动附加用户上下文字段：`email`、`user_email`、`userEmail`
- 示例：
```json
{
  "descriptions": ["Forest ambience with birds and light wind"],
  "duration": 12,
  "cfg_coef": 3
}
```

### 2.2 Continuation 续写生成
- 方法：POST
- 路径：`/audiogen/continuation`
- Content-Type：`multipart/form-data`
- 关键字段：
  - `descriptions` string
  - `prompt_audio` file（必填）
  - `duration` number
  - `cfg_coef` number

## 3. 异步任务接口

### 3.1 查询状态
- 方法：GET
- 路径：`/status/{request_id}`
- 返回核心字段：`status`、`progress`、`message`、下载地址相关字段。

### 3.2 取消任务
- 方法：POST
- 路径：`/cancel/{request_id}`

## 4. 辅助接口

### 4.1 AI 辅助
- 方法：POST
- 路径：`/ai-assist`
- 说明：`product` 会被归一化为 `soundscape`。

### 4.2 健康检查
- 方法：GET
- 路径：`/health`

### 4.3 历史记录（Studio 侧）
- 方法：GET
- 路径：`/music?page={page}&limit={limit}&product=soundscape`

## 5. 错误与重试建议
- 失败响应：前端优先显示 `detail`，其次 `message`。
- 队列中断：可调用取消接口后重新提交，避免残留任务占用。
- 对于续写模式，请确保 `prompt_audio` 文件可被读取且格式有效。