Suno 오디오 스템 분리
오디오 스템 분리 엔드포인트를 사용하여 비동기 Task를 생성하세요.
개요
필요한 입력값으로 오디오 스템 분리 엔드포인트를 사용하세요. 반환된 Task ID로 상태를 조회하거나, 아래에 문서화된 전달을 위해 callback_url을 제공하세요.
빠른 시작
- API 키를 만들고 RUNAPI_API_KEY로 설정합니다.
- 요청 스키마와 일치하는 본문으로 POST 요청을 전송하세요.
- 반환된 작업 ID를 저장한 후, 터미널 상태가 될 때까지 폴링하거나 아래에 문서화된 콜백을 처리하세요.
엔드포인트
- Base URL
https://runapi.ai- API 버전
v1- 인증
Authorization: Bearer YOUR_API_TOKEN
지원 모델
현재 가격, 속도 제한 및 상업적 이용 세부 정보는 모델 페이지를 여십시오.
요청 스키마
문서화된 필드만 전송하세요. callback_url이 제공된 경우 아래 문서화된 Task 전달을 수신합니다.
요청 본문필드 5개
audio_idstring소스 Task 내의 오디오 ID.
callback_urlstring비동기 알림을 위한 웹훅 URL.
stem_namestring고급 분리를 위한 대상 스템. type이 split_stem_advanced일 때 필수입니다.
허용 값:Lead Vocal, Drum Kit, Kick, Snare, Risers, Bass, Backing Vocals, Piano, Electric Guitar, Percussion, String Section, Synth, Acoustic Guitar, Sound Effects, Synth Pad, Synth Bass, Guitar, Brass Section, Organ, Electronic Drum Kit, Lead Electric Guitar, Synth Keys, Rhythm Electric Guitar, Electric Piano, Upright Bass, Keyboards, Distorted Electric Guitar, Synth Strings, Synth Lead, Woodwinds, Rhythm Acoustic Guitar, Flute, Harp, Tambourine, Trumpet, Arpeggiator, Accordion, Fiddle, Pedal Steel Guitar, Synth Voice, Violin, Digital Piano, Synth Brass, Mandolin, Choir, Banjo, Bells, Clarinet, Tenor Saxophone, Trombone, Shaker, French Horn, Glockenspiel, Electric Bass, Cello, Timpani, Harmonica, Marimba, Vibraphone, Lap Steel Guitar, Saxophone, Orchestra, Horns, Cymbals, Hand Clap, Oboe, Celesta, Congas, Drone, Alto Saxophone, Double Bass, Ukulele, Harpsichord, Baritone Saxophone, Xylophone, Tuba, Bass Guitar, Whistle, Lead Guitar, Rhodes, 808, Bongos, Bassoon, Cowbell, Viola, Sitar, Steel Drums, Piccolo, Theremin, Bagpipes, Hi-Hat, Music Box, Melodica, Tabla, Koto, Djembe, Taiko, Didgeridoo
task_idstring소스 태스크 ID.
typestring스템 분리 모드.
허용 값:separate_vocal, split_stem, split_stem_advanced
기본값: separate_vocal
조건부 규칙
이 요구 사항은 나열된 모든 조건이 일치할 때 적용됩니다.
-
다음의 경우
type = split_stem_advanced- 필수
stem_name- 허용되지 않음
수락 만들기
POST /api/v1/suno/separate_audio_stems
응답 스키마
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}
폴링 처리 중
GET /api/v1/suno/separate_audio_stems/:id
응답 스키마
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"separated_audios": {
"properties": {
"backing_vocals_url": {
"type": "string",
"x-runapi-generated-media": true
},
"bass_url": {
"type": "string",
"x-runapi-generated-media": true
},
"brass_url": {
"type": "string",
"x-runapi-generated-media": true
},
"drums_url": {
"type": "string",
"x-runapi-generated-media": true
},
"fx_url": {
"type": "string",
"x-runapi-generated-media": true
},
"guitar_url": {
"type": "string",
"x-runapi-generated-media": true
},
"instrumental_url": {
"type": "string",
"x-runapi-generated-media": true
},
"keyboard_url": {
"type": "string",
"x-runapi-generated-media": true
},
"pairs": {
"items": {
"properties": {
"extracted_audio": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration_seconds": {
"type": "number"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"duration_seconds",
"audio_url"
],
"type": "object",
"unevaluatedProperties": false
},
"remaining_audio": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration_seconds": {
"type": "number"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"duration_seconds",
"audio_url"
],
"type": "object",
"unevaluatedProperties": false
},
"stem_name": {
"type": "string"
}
},
"required": [
"stem_name",
"extracted_audio",
"remaining_audio"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"percussion_url": {
"type": "string",
"x-runapi-generated-media": true
},
"piano_url": {
"type": "string",
"x-runapi-generated-media": true
},
"strings_url": {
"type": "string",
"x-runapi-generated-media": true
},
"synth_url": {
"type": "string",
"x-runapi-generated-media": true
},
"vocal_url": {
"type": "string",
"x-runapi-generated-media": true
},
"woodwinds_url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"type": "object",
"unevaluatedProperties": false
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}
폴링 완료
GET /api/v1/suno/separate_audio_stems/:id
응답 스키마
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"separated_audios": {
"properties": {
"backing_vocals_url": {
"type": "string",
"x-runapi-generated-media": true
},
"bass_url": {
"type": "string",
"x-runapi-generated-media": true
},
"brass_url": {
"type": "string",
"x-runapi-generated-media": true
},
"drums_url": {
"type": "string",
"x-runapi-generated-media": true
},
"fx_url": {
"type": "string",
"x-runapi-generated-media": true
},
"guitar_url": {
"type": "string",
"x-runapi-generated-media": true
},
"instrumental_url": {
"type": "string",
"x-runapi-generated-media": true
},
"keyboard_url": {
"type": "string",
"x-runapi-generated-media": true
},
"pairs": {
"items": {
"properties": {
"extracted_audio": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration_seconds": {
"type": "number"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"duration_seconds",
"audio_url"
],
"type": "object",
"unevaluatedProperties": false
},
"remaining_audio": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration_seconds": {
"type": "number"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"duration_seconds",
"audio_url"
],
"type": "object",
"unevaluatedProperties": false
},
"stem_name": {
"type": "string"
}
},
"required": [
"stem_name",
"extracted_audio",
"remaining_audio"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"percussion_url": {
"type": "string",
"x-runapi-generated-media": true
},
"piano_url": {
"type": "string",
"x-runapi-generated-media": true
},
"strings_url": {
"type": "string",
"x-runapi-generated-media": true
},
"synth_url": {
"type": "string",
"x-runapi-generated-media": true
},
"vocal_url": {
"type": "string",
"x-runapi-generated-media": true
},
"woodwinds_url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"type": "object",
"unevaluatedProperties": false
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"separated_audios",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"separated_audios": {
"instrumental_url": "https://file.runapi.ai/reference-instrumental.mp3",
"vocal_url": "https://file.runapi.ai/reference-vocals.mp3"
},
"status": "completed"
}
폴링 실패
GET /api/v1/suno/separate_audio_stems/:id
응답 스키마
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}
고객 콜백: 완료됨
POST callback_url
응답 스키마
{
"properties": {
"id": {
"type": "string"
},
"separated_audios": {
"properties": {
"backing_vocals_url": {
"type": "string",
"x-runapi-generated-media": true
},
"bass_url": {
"type": "string",
"x-runapi-generated-media": true
},
"brass_url": {
"type": "string",
"x-runapi-generated-media": true
},
"drums_url": {
"type": "string",
"x-runapi-generated-media": true
},
"fx_url": {
"type": "string",
"x-runapi-generated-media": true
},
"guitar_url": {
"type": "string",
"x-runapi-generated-media": true
},
"instrumental_url": {
"type": "string",
"x-runapi-generated-media": true
},
"keyboard_url": {
"type": "string",
"x-runapi-generated-media": true
},
"pairs": {
"items": {
"properties": {
"extracted_audio": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration_seconds": {
"type": "number"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"duration_seconds",
"audio_url"
],
"type": "object",
"unevaluatedProperties": false
},
"remaining_audio": {
"properties": {
"audio_url": {
"type": "string",
"x-runapi-generated-media": true
},
"duration_seconds": {
"type": "number"
},
"id": {
"type": "string"
}
},
"required": [
"id",
"duration_seconds",
"audio_url"
],
"type": "object",
"unevaluatedProperties": false
},
"stem_name": {
"type": "string"
}
},
"required": [
"stem_name",
"extracted_audio",
"remaining_audio"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
},
"percussion_url": {
"type": "string",
"x-runapi-generated-media": true
},
"piano_url": {
"type": "string",
"x-runapi-generated-media": true
},
"strings_url": {
"type": "string",
"x-runapi-generated-media": true
},
"synth_url": {
"type": "string",
"x-runapi-generated-media": true
},
"vocal_url": {
"type": "string",
"x-runapi-generated-media": true
},
"woodwinds_url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"type": "object",
"unevaluatedProperties": false
},
"status": {
"enum": [
"completed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"separated_audios"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"id": "tsk_reference_demo",
"separated_audios": {
"instrumental_url": "https://file.runapi.ai/reference-instrumental.mp3",
"vocal_url": "https://file.runapi.ai/reference-vocals.mp3"
},
"status": "completed"
}
고객 콜백: 실패함
POST callback_url
응답 스키마
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}
오류
POST /api/v1/suno/separate_audio_stems
응답 스키마
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"error": "Authentication required"
}
오류
GET /api/v1/suno/separate_audio_stems/:id
응답 스키마
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"error": "Authentication required"
}
오류
POST /api/v1/suno/separate_audio_stems
응답 스키마
{
"oneOf": [
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 유효성 검사 요약입니다.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "공개 요청 필드를 키로 하는 유효성 검사 메시지로, 각 필드에 대해 사람이 읽을 수 있는 문자열 배열이 포함됩니다.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}
응답 예시
{
"error": "Validation failed",
"errors": {
"task_id": [
"is required"
]
}
}
오류
POST /api/v1/suno/separate_audio_stems
응답 스키마
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"error": "Insufficient balance"
}
오류
POST /api/v1/suno/separate_audio_stems
응답 스키마
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"error": "API key credit limit exceeded"
}
오류
POST /api/v1/suno/separate_audio_stems
응답 스키마
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"error": "The request uses features that are not supported for the selected model"
}
오류
POST /api/v1/suno/separate_audio_stems
응답 스키마
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"error": "Rate limit reached. Please retry later."
}
오류
POST /api/v1/suno/separate_audio_stems
응답 스키마
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"error": "Service under maintenance, please try again later"
}
오류
POST /api/v1/suno/separate_audio_stems
응답 스키마
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"error": "The request timed out"
}
오류
GET /api/v1/suno/separate_audio_stems/:id
응답 스키마
{
"properties": {
"error": {
"description": "사람이 읽을 수 있는 오류 메시지.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}
응답 예시
{
"error": "Task with id 'tsk_reference_demo' not found"
}
생성된 코드 샘플
cURL을 직접 사용하거나 해당 언어의 SDK를 설치하세요. 각 샘플은 이 레퍼런스에 표시된 유효성 검사된 요청을 제출합니다.
설치
pip install runapi-suno
import os
from runapi.suno import SunoClient
client = SunoClient(api_key=os.environ["RUNAPI_API_KEY"])
task = client.separate_audio_stems.create(
task_id="tsk_source_music",
audio_id="audio_reference",
type="separate_vocal"
)