# MusicPlus API 文档

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

## 2. 生成接口

### 2.1 文本生成（JSON）
- 方法：POST
- 路径：`/musicgen`
- Content-Type：`application/json`
- 关键字段：
  - `prompt` string 必填
  - `model_name` string（small/medium/melody/large）
  - `duration` number
  - `genre` string
  - `style` string
  - `tempo` string
  - `cfg_coef` number
  - `topk` number
  - `topp` number
  - `temperature` number
  - `seed` number
  - `filename` string
  - `return_file` boolean（前端固定 false）
- 自动附加用户上下文字段：`email`、`user_email`、`userEmail`
- 示例：
```json
{
  "prompt": "A lo-fi hip hop beat with smooth piano",
  "model_name": "medium",
  "duration": 30,
  "genre": "Lo-fi",
  "style": "Chill",
  "tempo": "90bpm",
  "cfg_coef": 3,
  "topk": 250,
  "topp": 0,
  "temperature": 1,
  "seed": -1,
  "filename": "lofi_night",
  "return_file": false
}
```

### 2.2 Melody 参考生成（Multipart）
- 方法：POST
- 路径：`/musicgen`
- Content-Type：`multipart/form-data`
- 关键字段：
  - 同 2.1 的核心字段
  - `melody_audio` file（可选）

### 2.3 长音频生成
- 方法：POST
- 路径：`/generate_long`
- Content-Type：`application/json`
- 触发条件：前端当 `duration > 30` 时使用该接口
- 关键字段：
  - `prompt` string
  - `model_id` string（facebook/musicgen-*）
  - `total_seconds` number
  - `guidance_scale` number
  - `chunk_seconds` number（默认 30）
  - `overlap` number（默认 5）
  - `top_k` number
  - `top_p` number
  - `temperature` number
  - `return_file` boolean

## 3. 异步任务接口

### 3.1 查询状态
- 方法：GET
- 路径：`/status/{request_id}`
- 典型返回字段：
  - `status`: `queued`/`processing`/`completed`/`error`/`cancelled`
  - `progress`: 0-100
  - `download_url` 或可下载文件字段
  - `message`（失败或阶段提示）

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

## 4. 辅助接口

### 4.1 AI 辅助提示词
- 方法：POST
- 路径：`/ai-assist`
- 说明：`product` 会被前端归一化为 `musicplus`

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

### 4.3 历史记录（Studio 侧）
- 方法：GET
- 路径：`/music?page={page}&limit={limit}&product=musicplus`
- 说明：用于历史页按产品筛选。

### 4.4 历史兼容别名（后端代理层）
- 方法：GET
- 路径（等价）：
  - `/music`
  - `/api/music`
  - `/history`
  - `/api/history`
- 说明：后端会统一代理到 Music 上游并返回标准化字段：`music`、`history`、`items`、`raw_items`、`count`。

### 4.5 单条与文件代理（后端代理层）
- 单条详情：
  - `GET /music/{music_id}`
  - `GET /api/music/{music_id}`
- 下载：
  - `GET /download-music/{music_id}`
  - `GET /api/download-music/{music_id}`
- 流式播放：
  - `GET /stream/{music_id}`
  - `GET /api/stream/{music_id}`

## 5. 响应处理约定
- 成功创建任务：返回 `request_id`。
- 若响应非 2xx，前端优先读取 `detail`，其次读取 `message`。
- 无 `request_id` 时视为初始化失败并报错。