API 레퍼런스고급 사용자업데이트
POST/v1/music/generations

Suno 음악 생성 API

Suno V6로 설명이나 직접 작성한 가사에서 곡을 생성할 수 있습니다. 보컬 없는 연주곡도 지원합니다.

기본 URL은 https://api.icodeeasy.cc입니다. 연결이 느리면 경로는 그대로 두고 https://jp.icodeeasy.cc 또는 https://sg.icodeeasy.cc를 사용하세요. 제출과 조회에는 모두 Authorization: Bearer <API 키>가 필요합니다.

생성 작업 제출

bash
curl -X POST https://api.icodeeasy.cc/v1/music/generations \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: music-demo-001' \
  -d '{"model":"suno","version":"v6","prompt":"A warm jazz trio with brushed drums","instrumental":true,"audio_format":"mp3"}'

HTTP 202가 반환됩니다. data[0].task_id를 저장해 작업을 조회하세요. 생성이 완료되면 곡을 받을 수 있습니다.

json
{"code":202,"data":[{"task_id":"mus_0123456789abcdef0123456789abcdef","status":"submitted","progress":0}]}

요청 매개변수

필드용도
modelsuno를 사용하며 생략할 수 있습니다.
versionv6(기본값), v6-wild, 또는 v6-mini.
customfalse(기본값)는 설명으로 생성하고 true는 직접 작성한 가사를 사용합니다.
prompt설명은 최대 3,000자이며 가사는 최대 5,000자입니다. custom과 instrumental이 모두 true이면 생략할 수 있습니다.
instrumentaltrue는 보컬 없는 연주곡을 생성합니다.
title / style사용자 지정 모드의 선택 항목인 곡 제목과 스타일입니다. 각각 최대 80자와 1,000자입니다.
audio_formatmp3(기본값), m4a, 또는 wav.

새 작업마다 128바이트 이하의 고유한 Idempotency-Key를 사용하세요. 제출 시간이 초과되거나 응답을 받지 못했다면 같은 요청 본문과 키로 다시 제출해 기존 작업을 찾을 수 있습니다. 다른 내용에 같은 키를 사용하면 HTTP 409가 반환됩니다.

작업 조회 및 곡 다운로드

bash
curl https://api.icodeeasy.cc/v1/music/tasks/mus_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

약 10초 간격으로 조회하세요. HTTP 200 응답의 data.status에서 작업 상태를 확인할 수 있습니다.

  • pending, submitted, processing인 동안 계속 조회하세요.
  • completed이면 data.result.music에서 생성된 모든 곡을 읽을 수 있습니다. 곡 수는 생성 결과에 따라 달라집니다.
  • failed는 작업이 실패했음을 뜻합니다. unknown은 제출 여부를 확인하지 못한 상태입니다. 작업 ID와 멱등성 키를 보관하고 새 키로 자동 재제출하지 마세요.

곡마다 audio_index, 초 단위의 duration, 재생용 서명 링크 audio_url이 제공됩니다. download_url이 있으면 다운로드에 사용하세요. title 및 lyrics가 포함될 수 있습니다. 서명된 링크는 API 키 없이 접근할 수 있으므로 비공개로 관리하세요. 링크가 만료되면 작업을 다시 조회해 새 링크를 받으세요.

완료된 작업의 응답 예시입니다. 금액은 필드 형식을 보여 주기 위한 예시입니다.

json
{
  "code": 200,
  "data": {
    "id": "mus_0123456789abcdef0123456789abcdef",
    "status": "completed",
    "model": "suno",
    "version": "v6",
    "progress": 100,
    "cost_rmb": 0.50,
    "result": {
      "music": [
        {
          "audio_index": 1,
          "duration": 138.5,
          "audio_url": "https://audio.example/track-1.mp3?signature=example",
          "download_url": "https://audio.example/track-1.mp3?download=1&signature=example"
        },
        {
          "audio_index": 2,
          "duration": 146.2,
          "audio_url": "https://audio.example/track-2.mp3?signature=example",
          "download_url": "https://audio.example/track-2.mp3?download=1&signature=example"
        }
      ]
    }
  }
}

요금

성공한 작업마다 한 번만 청구하며, 확정 금액은 위안화로 data.cost_rmb에 표시됩니다. 제출할 때 잔액을 미리 확보하고 작업이 실패하면 돌려줍니다. 조회와 다운로드에 추가 요금은 없습니다. 잔액이 부족하면 HTTP 402가 반환됩니다.