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

# Suno Studio 프로젝트 연동 가이드

> Suno Music Generation API guide - Ace Data Cloud

Suno Studio 프로젝트 API는 하나의 엔드포인트를 통해 멀티트랙 음악 프로젝트를 관리합니다:

```http theme={null}
POST /suno/projects
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

요청의 `action`이 작업 유형을 결정합니다. Project 기본 키는 모두 `id`를 사용합니다. `version_id`는 현재 프로젝트 버전을 나타내며, 모든 수정 및 내보내기 작업은 동시 덮어쓰기를 방지하기 위해 최신 버전을 제출해야 합니다.

## 작업 개요

| action | 모드 | 용도 |
| - | - | - |
| `create` | 동기 | 빈 프로젝트 생성 |
| `retrieve` | 동기 | 프로젝트 및 완전한 편집 가능 `state` 읽기 |
| `save` | 동기 | 전체 프로젝트 상태 저장 |
| `upload` | 비동기 | HTTPS 오디오 주소에서 프로젝트에 추가 가능한 소재 초기화 |
| `add_track` | 비동기 | 기존 오디오를 프로젝트에 추가 |
| `generate_track` | 비동기 | 지정 구간에 대한 새 오디오 트랙 후보 생성 |
| `replace_section` | 비동기 | 부분 교체 후보 생성 |
| `commit_candidate` | 비동기 | 선택한 후보를 프로젝트에 커밋 |
| `remove_track` | 동기 | 지정 트랙 삭제 |
| `render` | 비동기 | 저장된 버전을 완성된 곡으로 내보내기 |

비동기 작업은 즉시 `task_id`를 반환합니다. 무료 `/suno/tasks` 인터페이스를 사용하여 폴링하거나, `callback_url`을 전달하여 최종 상태 결과를 수신합니다.

## 생성 및 읽기

```json theme={null}
{"action":"create","title":"My Studio Project"}
```

모든 수정 작업은 고유한 `Idempotency-Key` Header를 전송해야 합니다. 생성 성공 후 응답의 `data.id`는 Project ID입니다. 새 빈 프로젝트는 최초 저장 전에는 `version_id`가 없을 수 있습니다.

```json theme={null}
{"action":"retrieve","id":"PROJECT_ID"}
```

읽기 응답에는 완전한 `state`가 포함됩니다. 새 빈 프로젝트는 `{"tracks":[],"timing":{"bps":2}}`를 반환하며, 이를 최초 저장에 직접 사용할 수 있습니다. `timing.bps`는 초당 박자 수를 나타내며, 기본값은 2(120 BPM)이고 양수여야 합니다. 클립의 `startBeats`, `endBeats`, `readStartBeats`는 프로젝트 박자 단위를 사용하므로, 오디오 분석의 마디 위치를 타임라인 좌표로 직접 사용할 수 없습니다.

## 전체 상태 저장

```json theme={null}
{
  "action":"save",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "title":"Edited Project",
  "state":{"tracks":[],"timing":{"bps":2}}
}
```

새 빈 프로젝트의 최초 저장 시 `version_id`는 생략할 수 있습니다. 최초 저장으로 버전이 생성된 후에는 이후 저장 시 최신 값을 제출해야 합니다. 버전이 이미 변경된 경우, 인터페이스는 HTTP 409를 반환합니다. 이때 다시 `retrieve`하고, 수정 사항을 병합한 후 새 멱등 키로 제출합니다. 이전 요청을 무작정 재시도하지 마세요.

## 업로드 및 트랙 추가

```json theme={null}
{
  "action":"upload",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "audio_url":"https://cdn.example.com/reference.mp3",
  "async":true
}
```

업로드 성공 후 `response.data.candidate.audio_id`에서 오디오 ID를 읽습니다. 그런 다음 이를 프로젝트에 추가합니다:

```json theme={null}
{
  "action": "add_track",
  "id": "PROJECT_ID",
  "version_id": "CURRENT_VERSION_ID",
  "audio_id": "AUDIO_ID",
  "name": "Backing Vocals"
}
```

트랙 추가는 기본적으로 오디오 재생 속도를 유지하고, 프로젝트 `timing.bps`에 따라 오디오 길이를 박자 수로 변환합니다. 각 `save`, `add_track`, `commit_candidate` 또는 `remove_track` 후에는 응답의 새 `version_id`를 사용해야 합니다.

## 생성 및 교체

`generate_track`은 프로젝트 구간에 대한 오디오 트랙 후보를 생성하고, `replace_section`은 두 개의 부분 교체 후보를 반환합니다. 두 작업 모두 예술적 결과를 자동으로 선택하지 않습니다. 모델은 반드시 공개 이름을 사용해야 합니다: `chirp-v3-5`, `chirp-v4`, `chirp-v4-5`, `chirp-v4-5-plus`, `chirp-v5`, `chirp-v5-5`, `chirp-v6`, `chirp-v6-wild` 또는 `chirp-v6-mini`. 구체적인 작업의 사용 가능 여부는 여전히 작업 최종 상태를 기준으로 하며, 지원되지 않는 이름은 제출 전에 400을 반환합니다. 다른 모델로 자동 전환되지 않습니다.

```json theme={null}
{
  "action":"replace_section",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "source_audio_id":"AUDIO_ID",
  "start_seconds":35.12,
  "end_seconds":48.76,
  "model":"chirp-v6",
  "replacement_lyrics":"新的歌词片段",
  "async":true
}
```

`generate_track`은 추가로 `render_audio_id`(완료된 프로젝트 내보내기 오디오), `stem_control_tags`, 그리고 소스 오디오 `source_audio_id`를 제공해야 합니다. `batch_size`는 1–4이며 기본값은 2입니다. `start_seconds`, `end_seconds`는 소스 오디오의 초 단위입니다. `fixed=true`인 교체 구간은 반드시 26초보다 짧아야 합니다.

후보 선택 후 커밋합니다:

```json theme={null}
{
  "action":"commit_candidate",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "operation_id":"OPERATION_ID",
  "candidate_id":"CANDIDATE_ID",
  "track_id":"TRACK_ID"
}
```

후보는 생성 시점의 프로젝트 버전에 연결됩니다. 프로젝트가 이미 변경된 경우 이전 후보를 직접 커밋할 수 없습니다.

부분 교체 후보는 고유한 소스 클립을 포함하는 원래 트랙에 커밋되며, 전체 take 후보는 원래 위치를 유지하면서 원래 클립을 교체합니다. 구간 후보는 요청 구간만 교체하고 앞뒤 클립은 유지합니다. 길이를 신뢰성 있게 일치시킬 수 없는 경우 400을 반환하고 원래 프로젝트를 유지합니다. 이때 `start_beats`, `end_beats`를 전달하지 마세요. 새 트랙 후보는 미리 저장된 빈 트랙에 커밋해야 하며, 기본적으로 소스 클립 시작점을 따르거나 겹치지 않는 범위를 명시적으로 전달합니다. 동일 트랙의 기존 클립과 겹치면 400을 반환합니다. 먼저 생성한 후 새 트랙을 만들지 마세요. 그렇지 않으면 버전 변경으로 후보가 만료됩니다.

## 완성된 곡 내보내기

```json theme={null}
{
  "action":"render",
  "id":"PROJECT_ID",
  "version_id":"CURRENT_VERSION_ID",
  "title":"Final Mix",
  "lyrics":"[Instrumental]",
  "async":true,
  "callback_url":"https://example.com/webhooks/suno"
}
```

서버는 지정된 버전의 권위 있는 프로젝트 상태를 읽고 내보내기 매개변수를 구성합니다. `start_beats`, `end_beats`를 생략하면 기본적으로 모든 들을 수 있는 클립의 가장 이른 시작점부터 가장 늦은 끝점까지 내보냅니다. 음소거 트랙/클립은 포함되지 않으며, solo 트랙이 존재할 경우 solo 트랙만 선택됩니다. 빈 프로젝트 또는 유효한 들을 수 있는 트랙이 없으면 400을 반환합니다. 최종 상태 결과에는 `render_id`, `audio_id`, `audio_url` 및 길이가 포함됩니다. 프로젝트는 생성 시의 실행 환경에 연결되며, 환경 간 마이그레이션 또는 자동 장애 조치를 할 수 없습니다.

> 합법적인 사용 권한을 보유한 오디오만 업로드하거나 처리할 수 있습니다. 프로젝트 API는 현재 Beta입니다. 중요한 결과의 최종 오디오 URL을 영구 저장하세요.

## 폴링 및 실패 복구

```json theme={null}
{"action":"retrieve","id":"TASK_ID"}
```

위의 요청을 `/suno/tasks`로 전송합니다. Projects 작업은 `finished_at`이 존재하고 `response.success=true`인 경우 성공을 의미하며, `response.success=false`는 실패를 의미합니다. 제출 시 반환되는 HTTP 200 또는 `task_id`는 접수되었음을 나타낼 뿐, 오디오가 완료되었음을 의미하지는 않습니다.

동일한 `Idempotency-Key`와 동일한 요청은 원래 결과(실패 포함)를 다시 읽어오며, 자동으로 재생성되거나 중복 청구되지 않습니다. 이미 실패한 작업을 명시적으로 재시도하려면 먼저 원래 작업을 조회하여 실패를 확인한 후 새 키를 사용하세요. 원래 작업이 아직 처리 중이거나 결과가 불확실한 경우에는 다시 제출하지 마세요.

오류 분류에는 `studio_unavailable` / `studio_model_unavailable`(503, 일시적으로 처리할 수 없거나 모델을 사용할 수 없음), `studio_model_unsupported`(400, 모델이 해당 작업을 지원하지 않음), `studio_state_invalid`(400, 프로젝트 상태 또는 내보내기 범위가 유효하지 않음), `too_many_requests`(429), `studio_audio_unavailable`(403, 참조 오디오를 프로젝트 내보내기에 사용할 수 없음), 그리고 `content_rejected`(403)가 포함됩니다. 조사 용도로 `trace_id`를 보존하세요.


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