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

# Suno 通用约定与任务查询

>  - Suno 音乐接口的公共说明：认证、异步任务生命周期、model / version、源音轨引用
- 任务查询：GET /v1/music/tasks/:task_id，轮询直到 completed / failed 

<Info>
  本页是所有 Suno 音乐接口的公共约定，配合每个端点单独文档使用。所有生成 / 编辑接口均为**异步任务**：提交拿 `task_id`，再轮询本页的查询接口取结果。
</Info>

## 认证

所有请求都需要在请求头中携带：

```
Authorization: Bearer <你的API Key>
Content-Type: application/json
```

访问 [API Key 管理页面](https://apimart.ai/keys) 获取 API Key。

## 任务生命周期（所有接口均为异步）

<Steps>
  <Step title="提交">
    `POST /v1/music/generations/<操作>` → 立即返回我方 `task_id`：

    ```json theme={null}
    { "code": 200, "data": [ { "status": "submitted", "task_id": "task_xxx" } ] }
    ```
  </Step>

  <Step title="轮询">
    `GET /v1/music/tasks/:task_id` 直到 `status` 为 `completed` 或 `failed`。生成中 `status` 为 `pending`，`progress` 排队 `10` → 就绪 `50` → 完成 `100`。建议轮询间隔 3–5s；音乐生成通常 30–120s。
  </Step>

  <Step title="取结果">
    完成后从 `data.result.music[]` 取 `audio_url` / `image_url` / `video_url` 等。
  </Step>
</Steps>

任务状态流转：`submitted` → `pending` → `completed` / `failed`。**失败时 `data.error.message` 给出原因，且预扣额度自动退回。**

## 版本 version

`v3.5` / `v4` / `v4.5` / `v4.5+` / `v4.5-all` / `v5` / `v5.5`，影响音质与计费；不传使用默认。各端点的可用版本与默认值不同——部分端点只支持子集，部分端点无版本维度；以各端点自身文档为准。

## 引用源音轨：task\_id + audio\_index

基于已有歌曲的操作（续写 / 翻唱 / 分轨 / 加人声 / 裁剪…）**不需要**记任何上游 id，只传：

* `task_id`：产出源音轨那次任务的我方 `task_id`
* `audio_index`：该任务结果 `music[]` 里第几首（1-based，默认 `1`；一次生成通常 2 首：1 和 2）

<Warning>
  无法解析源时（任务未完成 / 序号越界 / `task_id` 不存在），提交期直接返回 `400`。
</Warning>

## 查询任务：GET /v1/music/tasks/:task\_id

<ParamField path="task_id" type="string" required>
  提交接口返回的我方 `task_id`。
</ParamField>

轮询该接口直到 `status` 为 `completed` 或 `failed`。完成后从 `data.result.music[]` 取产物。

## Response

<ResponseField name="task_id" type="string">
  任务唯一标识符
</ResponseField>

<ResponseField name="status" type="string">
  任务状态：`submitted` / `pending` / `completed` / `failed`
</ResponseField>

<ResponseField name="progress" type="integer">
  进度：排队 `10` → 就绪 `50` → 完成 `100`
</ResponseField>

<ResponseField name="data" type="object">
  结果数据

  <Expandable title="属性">
    <ResponseField name="result" type="object">
      `status` 为 `completed` 时存在

      <Expandable title="result 属性">
        <ResponseField name="music" type="array">
          产物列表（一次生成通常 2 首）

          <Expandable title="music[] 属性">
            <ResponseField name="audio_id" type="string">
              音轨 id，供后续操作用 `audio_index` 定位
            </ResponseField>

            <ResponseField name="title" type="string">
              标题
            </ResponseField>

            <ResponseField name="duration" type="number">
              时长（秒）
            </ResponseField>

            <ResponseField name="lyrics" type="string">
              歌词
            </ResponseField>

            <ResponseField name="tags" type="string">
              风格标签
            </ResponseField>

            <ResponseField name="audio_url" type="string">
              音频文件 URL
            </ResponseField>

            <ResponseField name="image_url" type="string">
              封面图 URL
            </ResponseField>

            <ResponseField name="image_large_url" type="string">
              大图封面 URL
            </ResponseField>

            <ResponseField name="video_url" type="string">
              MV 视频 URL（若已生成）
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error" type="object">
      `status` 为 `failed` 时存在

      <Expandable title="error 属性">
        <ResponseField name="message" type="string">
          失败原因（预扣额度自动退回）
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json completed theme={null}
  {
    "task_id": "task_01ABC...",
    "status": "completed",
    "progress": 100,
    "data": {
      "result": {
        "music": [
          {
            "audio_id": "<音轨id，供后续操作 audio_index 定位>",
            "title": "Summer Breeze",
            "duration": 128.5,
            "lyrics": "……",
            "tags": "electronic, upbeat",
            "audio_url": "https://.../xxx.mp3",
            "image_url": "https://.../cover.png",
            "image_large_url": "https://.../cover_large.png",
            "video_url": "https://.../mv.mp4"
          }
        ]
      }
    }
  }
  ```

  ```json failed theme={null}
  {
    "task_id": "task_01ABC...",
    "status": "failed",
    "progress": 100,
    "data": {
      "error": {
        "message": "generation failed"
      }
    }
  }
  ```
</ResponseExample>