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

# 获取音乐任务状态

> 查询 Suno 音乐任务的状态和结果

<Note>
  **国内用户请注意：** 中国大陆用户请使用 `https://toapis.cn` 作为接口地址（Base URL）。文档示例中的 `https://toapis.com` 请替换为 `https://toapis.cn`。
</Note>

* 查询异步音乐任务的执行状态和结果
* 实时状态更新和进度跟踪
* 任务完成时获取音频、封面、视频等媒体 URL（已镜像本站 CDN)
* 任务失败自动退还费用

所有音乐任务都是异步执行的。提交任务后，请通过本接口轮询任务状态和结果。

## Authorizations

<ParamField header="Authorization" type="string" required>
  使用 Bearer Token 进行认证

  获取 API Key：访问 [API Key 管理页面](https://toapis.com/console/token)

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Path Parameters

<ParamField path="task_id" type="string" required>
  音乐生成接口返回的任务 ID(`tsk_aud_` 前缀）
</ParamField>

## Response

<ResponseField name="id" type="string">
  任务 ID
</ResponseField>

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

<ResponseField name="progress" type="integer">
  任务进度百分比（0-100)
</ResponseField>

<ResponseField name="cost" type="number">
  实际上游成本（美元）
</ResponseField>

<ResponseField name="created" type="integer">
  创建时间戳（Unix)
</ResponseField>

<ResponseField name="completed" type="integer">
  完成时间戳（Unix)
</ResponseField>

<ResponseField name="result" type="object">
  任务结果，结构随操作不同：

  <Expandable title="result 结构">
    <ResponseField name="music" type="array">
      曲目列表，每项含 `audio_url`、`image_url`、`title`、`tags`、`lyrics`、`duration` 等
    </ResponseField>

    <ResponseField name="instruments" type="array">
      `midi` 操作返回的分轨音符数据（`name`/`program`/`is_drum`/`notes[]`)
    </ResponseField>

    <ResponseField name="files" type="array">
      `download` 操作返回的多格式文件 URL 列表
    </ResponseField>

    <ResponseField name="videoUrl" type="string">
      `generateMp4` 返回的视频地址
    </ResponseField>

    <ResponseField name="avg_bpm" type="number">
      `bpm` 返回的平均 BPM（另有 `max_bpm`/`min_bpm`)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object">
  失败时的错误信息（`code`/`message`)
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://toapis.com/v1/music/tasks/tsk_aud_01M3EXAMPLE \
    --header 'Authorization: Bearer <token>'
  ```

  ```python Python theme={null}
  import time
  import requests

  task_id = "tsk_aud_01M3EXAMPLE"
  while True:
      resp = requests.get(
          f"https://toapis.com/v1/music/tasks/{task_id}",
          headers={"Authorization": "Bearer <token>"}
      ).json()["data"]
      if resp["status"] in ("completed", "failed"):
          break
      time.sleep(5)
  print(resp["result"])
  ```
</RequestExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.