TokenLab

미디어 가이드

음악 생성

곡이나 가사를 생성하고 완료된 오디오를 기다립니다

음악 생성은 비동기 방식으로 이루어집니다. POST /v1/music/generations는 작업 ID, 상태, 그리고 일반적으로 poll_url을 반환합니다. 작업이 completed 또는 failed 상태가 될 때까지 해당 ID로 GET /v1/tasks/{id}를 폴링(poll)하십시오.

생성할 항목 선택

생성 항목주요 필드참고 사항
전체 곡 또는 연주곡model, mv, prompt, 선택 사항 title, tags, action: "MUSIC"사용자가 최종 오디오를 기대할 때 사용
가사만 생성model, prompt, action: "LYRICS"가사 생성을 지원하는 모델에서만 사용
기존 클립 이어가기model, mv, prompt, continue_clip_id, 선택 사항 continue_at이전 클립 ID 유지
오디오 커버 또는 확장model, mv, prompt, audio_url, 선택 사항 audio_operationaudio_url은 공개 URL이어야 함. audio_operation은 기본값이 upload-cover이며, upload-extend는 continue_at이 필요함
연주곡 추가, 섹션 교체 또는 스템 분리audio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation, 또는 advanced-split각 작업마다 필요한 필드가 다름; 음악 생성 참조

다음에서 현재 음악 모델 목록을 가져옵니다:

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

아래 예시는 mv: "chirp-v6"를 사용하는 suno-music을 사용합니다. stable-audio-3와 같은 다른 음악 모델은 duration 및 output_format과 같은 다른 필드를 사용하므로, 먼저 해당 모델의 세부 정보를 읽어보십시오. 가사만 생성하려면 가사 생성을 지원하는 모델을 선택하고 action: "LYRICS"를 전송하며 mv는 생략하십시오.

음악 작업 생성

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-v6",
    "prompt": "An upbeat synth-pop track with warm vocals and a clean chorus",
    "title": "Morning Static",
    "tags": "synth-pop, upbeat",
    "action": "MUSIC"
  }'

프롬프트, 제목, 태그는 제품 기록에 나타날 수 있습니다. API 키, 비공개 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://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
  "video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
  "image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
  "title": "Morning Static",
  "lyrics": "[Verse 1]\n...",
  "media_retention": {
    "days": 30,
    "items": [
      {
        "url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
        "kind": "audio",
        "status": "saving",
        "expires_at": "2024-02-22T08:54:20.000Z"
      },
      {
        "url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
        "kind": "video",
        "status": "saving",
        "expires_at": "2024-02-22T08:54:20.000Z"
      },
      {
        "url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
        "kind": "image",
        "status": "saving",
        "expires_at": "2024-02-22T08:54:20.000Z"
      }
    ]
  }
}

최종 미디어 필드는 status가 completed가 될 때까지 나타나지 않습니다. 실패한 작업은 error와 함께 status: "failed"를 반환합니다.

상태는 pending, processing, completed, failed가 있습니다. 완료된 작업에는 audio_url, video_url, title, lyrics 및 기타 메타데이터가 포함될 수 있습니다. 미디어 URL은 30일 동안 유효한 TokenLab URL입니다. 더 오래 보관해야 하는 결과물은 다운로드하거나 저장하십시오.

올바른 상태 표시

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

청구 기록

음악 작업은 생성 시 예상 금액을 예약할 수 있습니다. 최종 금액은 완료 또는 실패 후에 기록됩니다. request_id, task_id, 모델, 엔드포인트 및 billing_transaction_id가 나타나면 이를 저장하십시오. 최종 청구에는 Management API 사용 기록을 사용하십시오.

일반적인 오류

증상예상 원인해결 방법
작업은 생성되었으나 플레이어가 없음작업이 여전히 대기 중이거나 audio_url 없이 완료됨종료 상태가 될 때까지 계속 폴링하고, 누락된 출력은 실패한 사용자 작업으로 처리
새로고침 후 곡이 중복됨UI가 작업을 재개하는 대신 새로 생성함task_id를 유지하고 재사용
가사 작업에서 오디오가 반환되지 않음action: "LYRICS"는 텍스트 전용임가사와 음악 UI 경로를 분리
지원되지 않는 매개변수선택한 모델이 해당 필드를 허용하지 않음제거하거나 해당 필드를 지원하는 모델을 선택

API 참조

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

이 페이지의 내용