# ArtistPro API 文档

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

## 2. 生成接口

### 2.1 专业生成（Multipart）
- 方法：POST
- 路径：`/jasco/expert`
- Content-Type：`multipart/form-data`
- 核心字段：
  - `prompt` string 必填
  - `chords` string（前端会先规范化）
  - `duration` number
  - `model_name` string（jasco-chords-drums-400M / jasco-chords-drums-1B）
  - `num_outputs` number（1-5）
  - `ode_solver` string（euler / dopri5）
  - `cfg_coef_all` number
  - `cfg_coef_txt` number
  - `ode_steps` number
  - `ode_rtol` number
  - `ode_atol` number
  - `use_chained` boolean
  - `drums_file` file（可选）
  - `melody_matrix_file` file（可选）
- 自动附加用户上下文字段：`email`、`user_email`、`userEmail`

## 3. 前端输入归一化规则
- 和弦支持两种输入：
  - 时间戳格式：`(C, 0.0), (G, 4.0)`
  - 简写格式：`C G Am F`
- 归一化后输出为 `(Chord, time)` 序列，最多 500 字符。
- 非法和弦格式会在前端直接拦截，不会调用接口。

## 4. 异步任务接口

### 4.1 查询状态
- 方法：GET
- 路径：`/status/{request_id}`

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

## 5. 辅助接口

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

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

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

## 6. 响应处理约定
- 成功创建任务：返回 `request_id`。
- 失败场景：前端使用 `detail`/`message` 提示。
- 建议在前端保留和弦示例，以减少参数校验失败。