음악 생성

음악 생성은 비동기적입니다. POST /v1/music/generations는 공개 TokenLab 작업을 생성하고 id / task_id, status, 그리고 일반적으로 poll_url을 반환합니다. 귀하의 애플리케이션은 해당 작업 식별자를 저장하고 진행 상황을 표시하며 최종 상태가 될 때까지 폴링해야 합니다.

워크플로우 선택

워크플로우	주요 필드	비고
전체 곡 또는 기악	`model`, `mv`, `prompt`, 선택적 `title`, `tags`, `action: "MUSIC"`	사용자가 최종 오디오를 기대할 때 사용
가사만	`model`, `prompt`, `action: "LYRICS"`	가사 생성을 노출하는 모델에서만 사용
기존 클립 계속하기	`continue_clip_id`, 선택적 `continue_at`	계속하기 전에 이전 공개 클립/작업 식별자를 저장

하드코딩된 모델 목록을 배포하기 전에 현재 모델 카탈로그를 쿼리하십시오:

curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"

현재 공개 예제는 음악 생성을 위해 suno_music을 사용하고 chirp-v4 같은 공식 Suno 모델 버전을 mv에 포함합니다. 가사 전용 흐름의 경우, 가사 생성을 문서화한 모델과 함께 action: "LYRICS"를 전송하고 mv는 생략하세요. 모델 ID는 공개 TokenLab ID로 취급하며, 제공자 특정 필드가 모델 세부정보 필드라는 보장은 아닙니다.

음악 작업 생성

curl 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-v4",
    "prompt": "따뜻한 보컬과 깔끔한 후렴이 있는 경쾌한 신스팝 트랙",
    "title": "아침의 정적",
    "tags": "신스팝, 경쾌한",
    "action": "MUSIC"
  }'

프롬프트, 제목 및 태그는 사용자에게 보이고 안전하게 저장할 수 있도록 유지하십시오. API 키, 개인 URL 또는 비공개 진단 정보를 어떤 프롬프트 필드에도 넣지 마십시오.

완료 폴링

먼저 poll_url을 사용하십시오. 클라이언트가 고정 경로가 필요하면 반환된 id 또는 task_id로 GET /v1/tasks/{id}를 호출하십시오.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

응답 형식

생성 응답은 최종 오디오가 아니라 폴링 가능한 작업 레코드입니다.

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "created": 1706000000,
  "model": "suno_music"
}

완료된 폴링 응답에는 최종 미디어 필드가 포함될 수 있습니다.

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "completed",
  "audio_url": "https://cdn.example.com/music/abc123.mp3",
  "video_url": "https://cdn.example.com/music/abc123.mp4",
  "stream_audio_url": "https://cdn.example.com/music/abc123-stream.mp3",
  "image_url": "https://cdn.example.com/music/cover.jpg",
  "title": "Morning Static",
  "lyrics": "[Verse 1]\n..."
}

최종 미디어 필드는 status가 completed가 되기 전에는 없습니다. 실패한 작업은 status: "failed"와 error를 반환합니다. 예상되는 공개 상태는 pending, processing, completed, 및 failed입니다. 완료된 음악 작업은 audio_url, video_url, title, lyrics, 및 정규화된 메타데이터를 포함할 수 있습니다. 최종 URL을 귀하의 데이터베이스에 저장하여 사용자가 결과를 다시 열 수 있도록 하십시오.

UI 및 상태 처리

작업 생성 직후에 대기 상태를 표시하십시오.
긴 작업의 경우 매 5-10초마다 폴링하고, completed 또는 failed 상태에서 중지하십시오.
작업이 completed되고 audio_url이 존재할 때까지 최종 플레이어를 표시하지 마십시오.
가사 전용 작업의 경우, 사용자가 구매하는 내용을 이해할 수 있도록 오디오 작업과 별도로 텍스트 출력을 렌더링하십시오.
새로 고침 시 새 작업을 생성하는 대신 저장된 task_id에서 계속하십시오.

청구 및 조정

음악 작업은 생성 시 예상 금액을 예약하고 최종 상태가 알려진 후에 정산할 수 있습니다. request_id, task_id, 모델, 엔드포인트, 및 billing_transaction_id가 나타날 때 저장하십시오. 제공자 작업 ID 대신 관리 API 사용 기록을 사용하여 조정하십시오.

일반 오류

증상	가능한 원인	수정
작업이 생성되었지만 플레이어 없음	작업이 여전히 대기 중이거나 `audio_url` 없이 완료됨	최종 상태까지 계속 폴링한 후, 누락된 출력을 실패한 사용자 작업으로 처리
새로 고침 후 중복 곡	UI가 작업을 재생성하여 계속하지 않음	`task_id`를 지속하고 재사용
가사 작업이 오디오를 반환하지 않음	`action: "LYRICS"`는 텍스트 전용	가사와 음악 UI 경로를 분리
지원되지 않는 매개변수	필드가 모델 모델 세부정보에 없음	제공자 특정 필드를 제거하거나 이를 문서화한 모델을 선택

API 참조

주제	참조
음악 생성	음악 생성
음악 상태 가져오기	음악 상태 가져오기
작업 상태 가져오기	작업 상태 가져오기
모델 목록	모델 목록
청구 및 가격 책정	청구 및 가격 책정

시작하기

핵심 가이드

미디어 가이드

워크플로우 선택

음악 작업 생성

완료 폴링

응답 형식

UI 및 상태 처리

청구 및 조정

일반 오류

API 참조

​워크플로우 선택

​음악 작업 생성

​완료 폴링

​응답 형식

​UI 및 상태 처리

​청구 및 조정

​일반 오류

​API 참조

워크플로우 선택

음악 작업 생성

완료 폴링

응답 형식

UI 및 상태 처리

청구 및 조정

일반 오류

API 참조