보이스 클론 및 지정 음색 생성 API(권장하지 않음)

2026-09-18 업데이트 · Suno-API 팀

⛔ 구 경로이므로 새 연동에는 권장하지 않습니다. 이 문서는 초기의 persona 경로(voice_task_id / generate-with-voice)를 설명합니다. 지금도 사용할 수 있지만 대외적으로 권장하지 않으며, 왼쪽 내비게이션에도 "권장하지 않음"으로 표시되어 있습니다.

새 연동에는 【권장】 음색 클론 API를 사용하세요. 보컬 샘플 하나로 음색을 만들고(POST /api/music/voice-profile/create), 그 음색으로 지정한 곡을 커버하거나 새 노래를 부르게 할 수 있습니다. 음색은 일급 리소스로 목록·조회·삭제가 가능하고 원본 오디오도 영구 보관됩니다.

"음색 생성 → 장기 재사용 → 커버"의 전체 흐름이 필요한 제품이라면 새 경로를 우선하세요.

중요: 복제한 음성은 만료될 수 있습니다.

음성 클로닝으로 생성된 voice_id / voice_task_id는 영구적으로 쓸 수 있는 리소스가 아닙니다. 유효 기간, 계정 상태, 음성 상태의 변화로 사용할 수 없게 될 수 있습니다. 연동하는 쪽은 최초 클로닝에 성공한 뒤 로컬에 캐시한 음성 ID를 계속 영구적으로 재사용해서는 안 됩니다.

권장 방식:

• voice_task_id, voice_id, is_available, updated_at, 최근 생성 성공 시각을 저장하세요.
• 복제한 음성으로 생성하기 전에 매번 GET /api/voice/clone/tasks/{voice_task_id} 또는 POST /api/voice/clone/tasks/{voice_task_id}/check를 호출해 is_available=true를 확인하세요.
• 음성을 사용할 수 없다는 오류, 작업이 존재하지 않는다는 오류, selected voice is not ready 등이 반환되면 사용자에게 다시 클로닝하거나 사용 가능한 다른 음성을 고르도록 안내하세요.
• 복제한 음성을 최종 사용자에게 "영구 자산"으로 약속하지 마세요. 제품 화면에서 "음성은 만료될 수 있으며 재검증 또는 재클로닝이 필요합니다"라고 안내하세요.

인터페이스 설명

이 그룹의 인터페이스는 재사용 가능한 음성을 만들고 그 음성으로 곡을 생성합니다. 호출하는 쪽은 플랫폼이 발급한 API Key만 사용하면 되고, 작업 제출·상태 동기화·과금·다운로드는 서버가 일괄 처리합니다.

인증 방식: Authorization: Bearer YOUR_API_KEY

과금:

• 음성 검증, 음성 클로닝, 상태 조회, 삭제, 다운로드: 무료.
• 워크스페이스의 원스텝 클론 진입점: 1회 5위안 고정. 원본 음성 검증과 2차 검증 오디오까지 자동으로 완료하며 실패하면 환불됩니다.
• 일반 클론 완료 후 곧바로 검증 오디오를 자동 생성하는 경우: 1회 5위안 고정. 실패하면 기존 흐름에 따라 환불됩니다.
• 복제한 음성으로 곡 생성: 유료, 1회 1.2위안 고정. 한 번의 호출로 보통 2건의 자리표시자 작업이 반환됩니다.
• Max Mode를 켜면(POST /api/music/generate-with-voice에 max_mode: true 전달) 위의 1회 1.2위안이 2배, 즉 1회 2.4위안으로 과금됩니다. 음성 생성도 variety(0-4, 추가 과금 없음)를 지원합니다. 값 규칙은 새 API 개요의 "고급 파라미터" 절을 참고하세요.

호출 흐름

1. POST /api/voice/clone/validate를 호출해 원본 음성을 업로드하고 voice_task_id를 받습니다.
2. GET /api/voice/clone/tasks/{voice_task_id}를 기다리거나 폴링해 validate_info를 받습니다.
3. 사용자가 validate_info를 읽고 검증 오디오를 녹음합니다.
4. POST /api/voice/clone/tasks/{voice_task_id}/generate를 호출해 검증 오디오를 제출합니다.
5. POST /api/voice/clone/tasks/{voice_task_id}/check를 호출하거나 작업을 계속 조회해 is_available=true가 될 때까지 기다립니다.
6. POST /api/music/generate-with-voice를 호출해 그 음성으로 곡을 생성합니다.
7. 생성 인터페이스는 먼저 자리표시자 작업을 반환합니다. 곡 생성이 끝나 실제 song_id를 받은 뒤에는 다운로드 인터페이스로 단일 파일이나 묶음 파일을 받을 수 있습니다.
8. (선택) 이 음성이 더 이상 필요 없으면 DELETE /api/voice/clone/voices/{voice_task_id}로 삭제합니다. 의미는 6절을 참고하세요.

원스텝 클론도 있습니다. 워크스페이스의 최초 녹음/원본 음성 업로드 화면에서 한 번에 완료를 선택하면 검증과 음색 생성을 한 번에 끝내므로 두 번째 검증 오디오를 녹음할 필요가 없습니다. 1회 5위안이며 실패하면 환불됩니다.

음성 작업 필드

1. 원본 음성 검증 제출

엔드포인트: POST /api/voice/clone/validate

Body 파라미터

vocal_end_s - vocal_start_s는 최소 보컬 구간 요건을 충족해야 합니다. 선명하고 눈에 띄는 반주나 잡음이 없는 보컬 녹음을 올리는 것을 권장합니다.

요청 예시

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "내 중국어 여성 음성",
    "description": "맑고 자연스러운 중국어 여성 음성",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "내 중국어 여성 음성",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. 음성 작업 조회

엔드포인트: GET /api/voice/clone/tasks/{voice_task_id}

요청 예시

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "내 중국어 여성 음성",
      "validate_info": "여기서 반환된 검증 텍스트를 읽어 주세요",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. 검증 텍스트 재생성

엔드포인트: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

검증 텍스트가 읽기에 적합하지 않거나 검증을 다시 해야 할 때 호출합니다.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. 검증 오디오 제출 및 음성 생성

엔드포인트: POST /api/voice/clone/tasks/{voice_task_id}/generate

Body 파라미터

요청 예시

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "내 중국어 여성 음성"
  }'

5. 음성 사용 가능 여부 확인

엔드포인트: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

작업이 사용 가능해지면 응답의 is_available이 true가 되고 voice_id가 반환됩니다.

6. 음성 삭제

엔드포인트: DELETE /api/voice/clone/voices/{voice_task_id}

과금: 무료.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

삭제하면 어떻게 되는가

• 새 곡 생성에 더 이상 쓸 수 없습니다: 이 voice_task_id(또는 그 voice_id)로 POST /api/music/generate-with-voice를 호출하면 거부되며 오류 메시지는 selected voice is not ready이고 과금되지 않습니다.
• 이미 이 음성으로 만든 곡은 전혀 영향을 받지 않습니다: 재생, 다운로드, 이어쓰기, 구간 교체, 스템 분리가 그대로 동작합니다.
• 이 음성 작업은 조회에서 사라집니다: GET /api/voice/clone/tasks/{voice_task_id}가 record not found를 반환합니다.
• 원본 오디오는 플랫폼의 영구 보관 정책에 따라 보관됩니다(2026-09-23부터 삭제해도 업로드한 보컬 소재를 정리하지 않습니다). 다만 복구할 수 있다는 뜻은 아닙니다: 이전 작업은 이미 종료되었고, 같은 목소리를 계속 쓰려면 클론 흐름을 다시 거쳐 **새 voice_task_id**를 받아야 합니다.
• 중복 삭제: 같은 작업을 다시 삭제하면 record not found가 반환됩니다(이미 삭제 상태라 조회되지 않습니다).

7. 복제한 음성으로 곡 생성

엔드포인트: POST /api/music/generate-with-voice

과금: 1회 1.2위안.

Body 파라미터

suno-v6, suno-v6-wild, suno-v6-mini를 지원하며 모델이 비어 있으면 suno-v6로 처리됩니다. 구형 V5/V5.5 모델은 종료되었지만 과거 작업에는 옛 모델명이 남아 있을 수 있습니다.

공유 요청 구조는 task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId, voiceId 같은 Create UI 호환 필드도 해석하지만, 이들은 이 인터페이스의 유효한 고객 파라미터가 아닙니다. 음성 작업은 반드시 voice_task_id로 전달하고, 선택적 음성 검증은 voice_id로 전달해야 하며, 음성 곡 생성이 sound 필드를 읽는 일은 없습니다.

생성 파라미터 작성 안내

• customMode=false일 때는 prompt에 곡 설명을, customMode=true일 때는 prompt에 전체 가사를 넣고 style과 title도 반드시 채워야 합니다. 가사를 간편 모드의 설명 필드로 잘못 보내거나 곡 설명을 고급 모드 가사로 취급하지 마세요.
• weirdnessConstraint와 styleWeight는 모두 0.0부터 1.0까지의 비율 소수이며 50이나 50%는 쓸 수 없습니다. 균형 값으로는 0.5를 쓸 수 있고, 생략은 "지정하지 않음"을, 0은 유효한 명시적 값을 뜻합니다.
• vocalGender에는 m, male, f, female만 쓸 수 있습니다. instrumental은 이 인터페이스에서 호환 필드일 뿐이며 복제 음성 생성은 항상 보컬 곡으로 처리됩니다.
• waitAudio는 이 인터페이스에서 동작을 바꾸지 않으며 항상 비동기로 자리표시자 작업을 반환합니다. 초기 결과의 audio_url이 비어 있는 것은 정상입니다. client_request_id로 조회하고 결과가 완료된 뒤에 오디오 주소를 읽으세요.

Header 파라미터

Idempotency-Key 동작:

• 첫 요청은 과금 전에 영구 멱등 레코드를 기록합니다.
• 같은 Key로 같은 요청이 이미 완료되면 첫 접수 응답을 재생하고, 다시 과금하거나 작업을 만들지 않습니다.
• 같은 Key에 요청 본문이 다르면 거부됩니다.
• 같은 Key가 아직 처리 중이면 안정적인 처리 중 오류를 반환하고, 생성된 경우에만 안전한 client_request_id를 반환합니다.
• 같은 Key의 첫 요청이 실패하면 실패 상태가 유지되며, 재시도에는 새 Key가 필요합니다.

sourceClipId 커버 조건

고객 API의 참조 원본 커버는 서버가 원본 곡 접근을 일괄 처리하므로 고객이 계정 정보를 전달할 필요가 없습니다. 사용 가능 여부는 실제 응답으로 판단하세요.

참조 원본은 현재 API 사용자에게 속하고, 완료되었으며 pending:이 아닌 워크스페이스 곡이고 사용 가능한 오디오가 있어야 합니다. 일반 생성, 일반 업로드 원본, 강화 업로드 최종 곡을 지원합니다. 강화 업로드의 중간 레코드는 과금 전에 거부됩니다. 서버는 고객이 제출한 원본 곡 ID만 받고 계정 ID는 받지 않으며, 원본을 쓸 수 없거나 미완료면 과금 전에 오류를 반환합니다.

요청 예시

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "여름밤 바닷가를 노래한 중국어 팝 곡을 써 주세요",
    "style": "Mandopop, warm piano, emotional",
    "title": "여름밤의 바닷바람",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "여름밤의 바닷바람",
        "prompt": "여름밤 바닷가를 노래한 중국어 팝 곡을 써 주세요"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "여름밤의 바닷바람",
        "prompt": "여름밤 바닷가를 노래한 중국어 팝 곡을 써 주세요"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

자리표시자 작업과 최종 song_id

generate-with-voice는 비동기 생성 인터페이스입니다. 성공 응답은 생성 작업이 접수되었다는 뜻일 뿐, 곡 생성이 끝났다는 뜻이 아닙니다.

응답의 주요 필드 의미:

주의: pending:으로 시작하는 placeholder_id는 최종 song_id로 쓸 수 없고 /api/music/query나 다운로드 인터페이스에 직접 넘길 수도 없습니다. pending:*만으로 /api/music/query를 호출하면 빈 배열 []이 반환될 수 있는데, 이는 실제 곡이 아직 완성되지 않았거나 자리표시자 작업이 최종 곡 ID로 바뀌지 않았기 때문입니다.

잘못된 예:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

올바른 흐름:

1. POST /api/music/generate-with-voice를 호출해 음성 곡 생성 작업을 제출합니다.
2. 응답의 client_request_id, items[].placeholder_id, items[].client_request_index를 저장합니다.
3. GET /api/music/generate-with-voice/results?client_request_id=cu_xxx를 폴링합니다.
4. 반환된 items[].song_id에 값이 있고 pending:으로 시작하지 않으면 /api/music/query, /api/music/download-file, /api/music/download-all을 호출합니다.

현재 버전에는 공개 조회 인터페이스가 추가되었습니다:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

현재 사용자에게 속한 같은 client_request_id의 작업 결과를 반환하므로 고객이 최종 song_id를 직접 조회할 수 있습니다. 반환 목록에서:

• song_id는 실제 곡 ID입니다.
• placeholder_id는 작업이 아직 자리표시자 상태일 때만 나타납니다.
• pending:으로 시작하는 값은 /api/music/query나 다운로드 인터페이스에 쓸 수 없습니다.

client_request_id나 pending:* 자리표시자 ID만 저장했다면 먼저 이 결과 인터페이스를 호출하세요. 실제 song_id가 아직 조회되지 않으면 client_request_id를 기술 지원에 보내 확인을 요청하세요.

음성 곡 생성 결과 조회

엔드포인트: GET /api/music/generate-with-voice/results

과금: 무료.

Query 파라미터

요청 예시

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

생성 중 응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "여름밤의 바닷바람"
      }
    ]
  }
}

생성 완료 응답 예시

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "여름밤의 바닷바람",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

최상위 status 의미

8. 단일 파일 다운로드

엔드포인트: POST /api/music/download-file

Body 파라미터

요청 예시

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

응답은 파일 스트림이며 Content-Type과 파일 이름은 백엔드가 반환한 값을 따릅니다.

9. 곡 리소스 묶음 다운로드

엔드포인트: POST /api/music/download-all

Body 파라미터

요청 예시

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

묶음 파일에는 보통 오디오, 커버, metadata.json이 들어 있습니다. 아직 생성되지 않은 종류의 리소스는 압축 파일에 포함되지 않습니다.

자주 발생하는 오류

이 그룹의 오류는 모두 HTTP 200으로 반환됩니다. 성공 여부는 응답 본문의 success 필드로 판단하세요(false가 실패이고 원인은 message). HTTP 상태 코드만 보고 판단하지 마세요. 음성 삭제의 전체 의미(삭제 후에도 쓸 수 있는지, 복구할 수 있는지)는 6절을 참고하세요.