> ## 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 음악 생성 — 영감/커스텀 가사 모드, Max 티어 지원

* 텍스트 설명 또는 커스텀 가사로 완성곡 생성(요청당 2개 후보)
* 비동기 태스크, 태스크 ID로 결과 폴링
* `custom`이 `prompt`의 의미를 결정: 커스텀 가사 vs 영감 설명

## Authorizations

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

## Body

<ParamField body="model" type="string" required>고정값 `"suno"`</ParamField>

<ParamField body="custom" type="boolean">
  모드 스위치, 기본 `false`

  * `false`: 영감 모드 — `gpt_description`(또는 `prompt`)에 음악 설명
  * `true`: 커스텀 가사 모드 — `prompt`가 가사 본문, `title`/`style`/`negative_tags` 적용
</ParamField>

<ParamField body="gpt_description" type="string">
  영감 모드의 음악 설명. 예:`"비 오는 밤 카페에 어울리는 lo-fi"`. 커스텀 모드에서는 불필요
</ParamField>

<ParamField body="prompt" type="string">
  커스텀 모드의 가사 본문(`[Verse]`/`[Chorus]` 구조 태그 지원)
</ParamField>

<ParamField body="title" type="string">곡 제목(커스텀 모드)</ParamField>
<ParamField body="style" type="string">스타일 태그(커스텀 모드). 예:`"dreamy synthwave, female vocal"`</ParamField>
<ParamField body="negative_tags" type="string">피할 요소(커스텀 모드)</ParamField>
<ParamField body="instrumental" type="boolean">보컬 없는 연주곡 생성</ParamField>
<ParamField body="version" type="string">엔진 버전:`v6` / `v6-wild` / `v6-mini`</ParamField>
<ParamField body="max_mode" type="boolean">Max 품질 티어(2배 \$0.10). `custom=true` 필요</ParamField>
<ParamField body="persona_id" type="string">생성된 보컬 페르소나 ID. `custom_model_id`와 상호 배타</ParamField>
<ParamField body="custom_model_id" type="string">커스텀 학습 모델 ID. `version`·`persona_id`와 상호 배타</ParamField>

### 선택적 튜닝 파라미터

`style_weight`, `weirdness`, `audio_weight`, `vocal_gender`, `auto_lyrics`, `variety`는 모두 선택 사항이며 생략 시 업스트림 기본값 적용.

## Response

<ResponseField name="task_id" type="string">
  태스크 ID(`tsk_aud_` 접두사). [태스크 상태 조회](/docs/ko/api-reference/tasks/music-status)로 폴링
</ResponseField>

<ResponseField name="status" type="string">`submitted` / `queued` / `in_progress`</ResponseField>

완료 후 `result.music[]`에 2개 후보가 반환되며 각각 `audio_url`, `image_url`, `title`, `tags`, `lyrics`, `duration` 포함. 미디어 URL은 CDN에 미러링됩니다.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://toapis.com/v1/music/generations/generation \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "suno",
      "gpt_description": "비 오는 밤 카페에 어울리는 lo-fi 재즈",
      "instrumental": false,
      "version": "v6"
    }'
  ```

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

  resp = requests.post(
      "https://toapis.com/v1/music/generations/generation",
      headers={"Authorization": "Bearer <token>"},
      json={
          "model": "suno",
          "custom": True,
          "prompt": "[Verse]\n네온이 켜진다\n[Chorus]\n새벽까지 달려간다",
          "title": "네온 라이드",
          "style": "synthwave",
          "max_mode": True
      }
  )
  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const resp = await fetch("https://toapis.com/v1/music/generations/generation", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "suno",
      gpt_description: "dreamy synthwave with female vocals",
      version: "v6-wild"
    })
  });
  console.log(await resp.json());
  ```
</RequestExample>


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