TokenLab

음악

음악 생성

음악, 가사 또는 사운드 생성 작업을 생성합니다

POST
/v1/music/generations

현재 음악 모델을 확인하려면 GET /v1/models?recommended_for=music을 사용하세요.

AI를 사용하여 음악, 가사 및 사운드를 생성합니다. 이 API는 비동기식 API입니다. 생성 응답으로 작업 식별자가 반환됩니다. 이 식별자를 사용하여 GET /v1/tasks/{id}를 폴링하여 상태를 확인하세요.

모델마다 허용하는 필드가 다릅니다. 선택적 필드를 전송하기 전에 GET /v1/models/{model}을 확인하세요. 모델에 나열되지 않은 필드는 400 unsupported_parameter를 반환할 수 있습니다. Suno 필드(mv, title, tags, negative_tags, audio_operation 및 관련 필드)는 Suno 모델에 적용됩니다. user는 지원되지 않으며 400을 반환합니다.

요청 본문

modelstring기본값: suno-music

suno-music 또는 stable-audio-3과 같은 음악 모델 ID입니다. 명시적으로 전달해야 합니다. 가사만 생성하는 경우 현재 공개 작업에 lyrics가 포함된 모델을 선택하세요.

promptstring

음악 설명 또는 대체 텍스트입니다. 음악, 가사, upload-cover, upload-extend 및 replace-section의 경우 필수이며, add-instrumental 및 스템 분리(stem separation)의 경우 선택 사항입니다.

titlestring

생성될 곡의 제목입니다.

tagsstring

스타일 태그입니다(예: "pop, upbeat, electronic").

negative_tagsstring

제외할 스타일입니다. audio_operation이 add-instrumental인 경우 필수입니다.

actionstring

선택적 MUSIC 또는 LYRICS 값입니다. 해당 공개 작업을 지원하는 모델을 선택하세요. 이 필드가 음악 전용 모델에 가사 지원 기능을 추가하지는 않습니다.

mvstring

Suno 버전 선택자입니다. 생성, upload-cover, upload-extend, add-instrumental 및 audio_url을 통한 대체 시 필수입니다. 가사, task_id + audio_id를 통한 대체, 스템 분리 시에는 생략합니다. 허용되는 값: chirp-v6, chirp-v6-mini, chirp-v6-wild.

make_instrumentalboolean

보컬 없이 연주곡(instrumental)만 생성하려면 true로 설정하세요.

audio_urlstring

공개적으로 접근 가능한 참조 또는 업로드된 오디오 URL입니다. audio_operation 없이 제공되면 TokenLab은 upload-cover 플로우를 사용합니다.

audio_operationstring

오디오 작업 유형: upload-cover, upload-extend, add-instrumental, replace-section, vocal-separate, multi-stem-separation, advanced-split.

vocal-separate, multi-stem-separation, advanced-split은 task_id + audio_id가 필요하며, advanced-split은 stem_name도 필요합니다. upload-extend는 0보다 큰 continue_at이 필요합니다. add-instrumental은 audio_url, title, tags, negative_tags가 필요합니다.

replace-section의 경우 prompt, tags, title, infill_start_s, infill_end_s, full_lyrics를 전송하세요. 소스는 task_id + audio_id 또는 audio_url + mv 중 정확히 하나만 선택해야 합니다. 대체 구간은 6~60초 사이여야 합니다.

task_idstring

생성된 오디오 대체 또는 스템 분리를 위한 조직 소유의 소스 작업 ID입니다.

audio_idstring

소스 작업 결과에서 반환된 소스 오디오 ID입니다. 생성된 오디오 대체 및 스템 분리 시 task_id와 함께 필수입니다.

infill_start_snumber

대체 시작 시간(초 단위)이며, 0 이상이어야 합니다. replace-section에 필수입니다.

infill_end_snumber

대체 종료 시간(초 단위)입니다. replace-section에 필수이며, infill_start_s로부터 6~60초 후여야 합니다.

full_lyricsstring

결과 곡의 전체 가사입니다. replace-section에 필수입니다.

stem_namestring

스템 이름입니다. advanced-split에 필수입니다.

continue_clip_idstring

이어서 진행할 이전 클립의 ID입니다.

continue_atnumber

이어갈 시작 시간(초 단위)입니다. upload-extend 시 필수이며 0보다 커야 합니다.

durationinteger

생성될 오디오의 길이(초 단위, 1~380초)입니다. stable-audio-3과 같이 이 필드를 지원하는 모델에만 해당하며, 세부 한도는 모델 정보에 명시되어 있습니다.

output_formatstring

모델이 나열한 오디오 파일 형식입니다(예: mp3, wav, flac). 이를 지원하는 모델에만 해당합니다.

seedinteger

결과 재현을 위한 시드 값(0~4294967294)입니다. 해당 필드를 지원하는 모델에만 적용됩니다.

stepsinteger

생성 단계(generation steps)의 수입니다. 범위는 모델에 따라 다릅니다(예: stable-audio-3의 경우 4에서 8). 해당 필드를 나열하는 모델에 대해서만 사용 가능합니다.

일부 모델은 negative_prompt, n, seconds, guidance_scale과 같은 추가 필드를 나열합니다. 모델 세부 정보에 해당 필드가 명시된 경우에만 전송하십시오. 선택한 모델이 지원하지 않는 필드를 전송할 경우 400 오류가 반환됩니다.

cfg_scalenumber

프롬프트 반영 강도(1~25)입니다. 해당 필드를 지원하는 모델에만 적용됩니다.

prompt는 최대 5000자까지 허용되며, tags 및 negative_tags는 각각 최대 1000자까지 허용됩니다. 지원되는 작업 및 파라미터는 선택한 모델의 현재 세부 정보에 따라 달라집니다.

응답

idstring

상태 폴링을 위한 작업 ID입니다.

task_idstring

반환되는 경우, 동일한 비동기 작업 ID의 별칭입니다.

poll_urlstring

이 작업의 상태 URL입니다. id를 사용하여 GET /v1/tasks/{id}를 폴링하세요.

statusstring

작업 상태: pending, processing, completed 또는 failed.

createdinteger

반환되는 경우, Unix 타임스탬프 형식의 작업 생성 시간입니다.

요청

curl -X POST "https://api.tokenlab.sh/v1/music/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-music",
    "mv": "chirp-v6",
    "prompt": "An upbeat electronic dance track with heavy bass",
    "title": "Night Drive",
    "tags": "electronic, EDM, energetic"
  }'

Suno 필드 대신 duration 및 output_format을 사용하는 모델의 사운드 생성 예시:

{
  "model": "stable-audio-3",
  "prompt": "Warm lo-fi beat with soft vinyl crackle",
  "duration": 30,
  "output_format": "mp3"
}

응답

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "suno-music"
}

인증

BearerAuth
AuthorizationBearer <token>

API 키 인증입니다. Dashboard > API > API Keys에서 API 키를 생성하거나 관리하십시오.

위치: header

헤더

X-TokenLab-Delivery-Policy?string

요청별 전송 정책입니다. API 키 및 Workspace 기본값을 재정의합니다. 자동으로 TokenLab Verified를 먼저 시도하며, 출력, 요청 수락 또는 영구 리소스 생성 전에 Official 전용으로 한 번 전환될 수 있습니다.

허용 값

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

생성 요청을 안전하게 재시도할 수 있게 하는 선택적 키입니다. 각 작업마다 UUID와 같은 새로운 고유 값을 전송하십시오. 동일한 키와 동일한 본문으로 재시도하면 원래 생성 요청의 결과(일반적으로 원래 작업)가 반환되며, 두 번째 작업이 생성, 발송 또는 청구되지 않습니다. 이미 수락된 키와 다른 본문을 전송하면 409 오류가 발생합니다. 255자를 초과하는 키는 무시되며, 해당 요청은 멱등성 보호를 받지 못합니다. 멱등성 키를 사용한 안전한 재시도를 참조하십시오.

길이1 <= length <= 255

요청 본문

application/json

응답

application/json

application/json

application/json

application/json

application/json

application/json