> ## 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 음악 태스크의 상태와 결과 조회

* 비동기 음악 태스크의 상태와 결과 조회
* 실시간 진행률 추적
* 완료 시 오디오·커버·영상 URL 획득(CDN 미러)
* 실패 태스크 자동 환불

모든 음악 태스크는 비동기로 실행됩니다. 제출 후 본 엔드포인트로 폴링하세요.

## Authorizations

<ParamField header="Authorization" type="string" required>
  Bearer Token. API Key:[API Key 관리 페이지](https://toapis.com/console/token)
</ParamField>

## Path Parameters

<ParamField path="task_id" type="string" required>
  음악 생성 API가 반환한 태스크 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">실제 업스트림 비용(USD)</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`:영상 URL</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.