> ## Documentation Index
> Fetch the complete documentation index at: https://doc.octopusx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno 音乐生成

> 使用 `/suno/*` 路由提交异步音乐任务，并查询歌词或音频生成结果。

# Suno 音乐生成

Suno 路由采用独立的异步任务协议，提交与查询都不走 `/v1/audio/*`。

* 一个入口覆盖自动作曲、歌词生成和自定义歌词生曲。
* 异步处理模式，提交后返回任务 ID。
* 支持单任务查询和批量查询。
* 查询结果使用 `code`、`message`、`data` 包装。

## 路由清单

| Method | Path                    | 说明     |
| ------ | ----------------------- | ------ |
| `POST` | `/suno/submit/{action}` | 提交音乐任务 |
| `GET`  | `/suno/fetch/{id}`      | 查询单任务  |
| `POST` | `/suno/fetch`           | 批量查询   |

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Path Parameters

<ParamField body="action" type="string" required>
  操作类型。常见值为 `music`、`lyrics`、`custom`。
</ParamField>

## Body

<ParamField body="prompt" type="string" required>
  `music` 模式下表示音乐描述；`custom` 模式下通常直接传歌词内容。
</ParamField>

<ParamField body="tags" type="string">
  风格标签，逗号分隔。
</ParamField>

<ParamField body="title" type="string">
  歌曲标题。
</ParamField>

<ParamField body="mv" type="string">
  模型版本，例如 `chirp-v3-5` 或 `chirp-v4`。
</ParamField>

<ParamField body="continue_clip_id" type="string">
  续写已有音乐片段时使用的 clip ID。
</ParamField>

## 请求示例

```bash theme={null}
curl -X POST https://octopusx.ai/suno/submit/music \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一首关于夏夜海边的轻快流行歌曲",
    "tags": "pop, summer, beach",
    "title": "海边的夏夜",
    "mv": "chirp-v3-5"
  }'
```

## 响应示例

<ResponseExample>
  ```json 200 - 提交成功 theme={null}
  {
    "code": "success",
    "message": "",
    "data": "task-suno-abc123"
  }
  ```

  ```json 200 - 查询成功 theme={null}
  {
    "code": "success",
    "message": "",
    "data": {
      "task_id": "task-suno-abc123",
      "status": "SUCCESS",
      "progress": "100%",
      "result_url": "https://.../audio/abc123.mp3"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "code": "task_not_exist",
    "message": "task_not_exist",
    "data": null
  }
  ```
</ResponseExample>

## 使用场景

### 自动作曲

```bash theme={null}
curl -X POST https://octopusx.ai/suno/submit/music \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一首适合产品发布会开场的电子流行乐",
    "tags": "electronic, upbeat"
  }'
```

### 批量查询

```bash theme={null}
curl -X POST https://octopusx.ai/suno/fetch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["task-suno-abc123", "task-suno-def456"]
  }'
```

## 相关接口

* [OpenAI 音频兼容接口](./audio)
* [任务管理概览](../tasks/overview)