Suno 生成歌曲（music） - 数字先锋API文档

# Suno 生成歌曲（music）接口文档

Base URL:
```text
https://api.cxsee.com
```

认证方式：
- 所有接口都需要在 Header 中携带 Bearer Token

```http
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
```

---

## 1. 提交生成任务

### 接口
`POST /suno/submit/music`

### 请求头
```http
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
```

### 请求体参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| model | string | 是 | 固定传 `suno_music` |
| prompt | string | 是 | 音乐描述提示词（支持中文/英文） |
| make_instrumental | bool | 否 | 是否纯音乐，`true`=无歌词，默认 `false` |

### 请求示例
```bash
curl -sS -X POST 'https://api.cxsee.com/suno/submit/music' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"suno_music",
    "prompt":"写一段轻快电子风旋律",
    "make_instrumental": true
  }'
```

### 返回示例
```json
{
  "code": "success",
  "data": "205a4029-d9ad-492a-8fb6-f556cc5718b5",
  "message": ""
}
```

### 返回说明
- `data` 为任务 ID（`task_id`），用于后续查询结果。

---

## 2. 查询任务结果

### 接口
`GET /suno/fetch/{task_id}`

> 例如：`/suno/fetch/205a4029-d9ad-492a-8fb6-f556cc5718b5`

### 请求头
```http
Authorization: Bearer <YOUR_API_KEY>
Accept: application/json
```

### 请求示例
```bash
curl -sS 'https://api.cxsee.com/suno/fetch/205a4029-d9ad-492a-8fb6-f556cc5718b5' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Accept: application/json'
```

### 返回示例（成功）
```json
{
  "code":"success",
  "message":"",
  "data":{
    "task_id":"205a4029-d9ad-492a-8fb6-f556cc5718b5",
    "action":"MUSIC",
    "status":"SUCCESS",
    "progress":"100%",
    "data":[
      {
        "id":"e05c9fc6-f875-4038-b2ac-b05cd6af32f3",
        "audio_url":"https://cdn1.suno.ai/e05c9fc6-f875-4038-b2ac-b05cd6af32f3.mp3",
        "image_url":"https://cdn2.suno.ai/image_e05c9fc6-f875-4038-b2ac-b05cd6af32f3.jpeg",
        "title":"",
        "prompt":"写一段轻快电子风旋律",
        "model_name":"chirp-v3",
        "duration":205.32
      }
    ]
  }
}
```

### 任务状态说明

| status | 说明 |
|---|---|
| PENDING / SUBMITTED | 已提交，排队中 |
| RUNNING / PROCESSING | 生成中 |
| SUCCESS | 生成成功，可读取音频链接 |
| FAIL / FAILED | 生成失败，查看 `fail_reason` |

---

## 3. 建议的调用流程

1. 调用 `POST /suno/submit/music` 提交任务，拿到 `task_id`
2. 每 3~5 秒调用一次 `GET /suno/fetch/{task_id}`
3. 当 `status=SUCCESS` 时，读取 `data[].audio_url` 作为音频下载/播放地址

---

## 4. 错误码约定（建议）

| code | 含义 |
|---|---|
| success | 请求成功 |
| invalid_request | 参数错误 |
| unauthorized | 鉴权失败（API Key 无效） |
| forbidden | 无权限 |
| not_found | 任务不存在 |
| rate_limited | 请求过于频繁 |
| server_error | 服务内部错误 |

---

## 5. 对接注意事项

- `task_id` 请持久化保存，避免查询丢失。
- 生成结果通常包含 1~2 首候选音频（`data` 数组）。
- 建议前端直接播放 `audio_url`，并缓存 `image_url` 作为封面。
- 若长时间未完成（如超过 3~10 分钟），可提示用户稍后重试。

---

上一篇：Suno 生成歌词（lyrics）下一篇：可灵（Kling）绘画