효과음 생성 API
인터페이스 설명
효과음 생성은 몇 초짜리 효과음을 만드는 것이며 곡이 아닙니다. 천둥, 빗방울, 충돌음 같은 짧은 소리에 적합하고, 전환 효과음, 환경음, 드럼 루프에도 쓸 수 있습니다. 대부분 5초 이내이고 최장 20초 정도이며, 단발과 루프 두 가지 모드를 지원합니다.
엔드포인트: POST /api/music/sounds
과금: 유료. 현재 기본 0.6 위안/회. 실제 청구 금액은 현재 백오피스 가격 설정을 따릅니다.
대기 시간과 타임아웃(중요): 이 엔드포인트는 동기 방식이며, 응답이 돌아온 시점에야 주문이 접수되어 생성에 넘겨집니다. 실측 기준 대부분의 요청은 1~3초에 반환되고, 약 10%는 30초를 넘기며, 최장 약 230초가 걸립니다. 클라이언트 타임아웃을 300초 이상으로 설정하세요. 응답이 없다고 해서 생성되지 않은 것이 아니며, 타임아웃 직후 재시도하면 주문이 중복되고 요금이 두 번 청구됩니다. 연결이 끊겼다면 잠시 후
GET /api/music/songs로 확인할 수 있습니다. 자세한 내용은 새 API 개요의 "대기 시간과 타임아웃 설정"을 참고하세요.
요청 파라미터
Headers
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| Authorization | string | 예 | Bearer YOUR_API_KEY |
| Content-Type | string | 예 | application/json |
바디 파라미터
| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| model | string | 아니오 | suno-v6 | 대고객 모델명: suno-v6, suno-v6-wild, suno-v6-mini |
| description | string | 예 | - | 원하는 소리를 설명합니다. 짧은 영어 구문이 가장 안정적입니다. 예: cinematic whoosh transition, bright impact |
| title | string | 아니오 | - | 제목. 생략하면 설명을 바탕으로 생성할 수 있습니다 |
| type | string | 아니오 | one_shot | 유형: one_shot(단발), loop(루프) |
| loop | boolean | 아니오 | false | 루프 여부. type을 loop로 쓰는 것과 같습니다 |
| bpm | number | 아니오 | - | BPM. 0보다 큰 숫자여야 합니다. 잘못된 값은 조용히 무시되지 않고 400(invalid_sound_bpm)을 반환합니다 |
| key | string | 아니오 | - | 조성. 음이름(C-B) + 선택적 #/b + 선택적 Major/Minor 형식이며 예: C Major, C#m, Bb. 비우거나 any면 지정하지 않음을 뜻합니다. 잘못된 값은 400(invalid_sound_key)을 반환합니다 |
요청 예시
curl -X POST https://www.suno-api.io/api/music/sounds \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-v6",
"description": "cinematic whoosh transition, bright impact",
"title": "cinematic whoosh",
"type": "one_shot",
"loop": false,
"bpm": 120,
"key": "C"
}'
응답 결과
곡 배열이 반환됩니다. 필드는 새 API 개요의 공통 곡 반환 필드와 동일합니다.