> ## 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 음악 API의 공통 설명: 인증, 비동기 작업 생명주기, model / version, 소스 오디오 트랙 참조
- 작업 조회: GET /v1/music/tasks/:task_id, completed / failed 될 때까지 폴링 

<Info>
  이 페이지는 모든 Suno 음악 API의 공통 규약이며, 각 엔드포인트의 개별 문서와 함께 사용합니다. 모든 생성 / 편집 API는 **비동기 작업**입니다: 제출하여 `task_id`를 받은 뒤, 이 페이지의 조회 API를 폴링하여 결과를 가져옵니다.
</Info>

## 인증

모든 요청은 요청 헤더에 다음을 포함해야 합니다:

```
Authorization: Bearer <당신의 API Key>
Content-Type: application/json
```

[API Key 관리 페이지](https://apimart.ai/keys)에 접속하여 API Key를 발급받으세요.

## 작업 생명주기 (모든 API는 비동기)

<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부터 시작, 기본값 `1`; 한 번의 생성은 보통 2곡: 1과 2)

<Warning>
  소스를 확인할 수 없는 경우 (작업 미완료 / 인덱스 범위 초과 / `task_id` 미존재) 제출 시점에 `400`을 반환합니다.
</Warning>

## 작업 조회: GET /v1/music/tasks/:task\_id

<ParamField path="task_id" type="string" required>
  제출 API가 반환한 당사의 `task_id`.
</ParamField>

이 API를 `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": "<track id, used with audio_index to locate it for subsequent operations>",
            "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>