미디어 가이드
음악 생성
곡이나 가사를 생성하고 완료된 오디오를 기다립니다
음악 생성은 비동기 방식으로 이루어집니다. 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_operation | audio_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 참조
| 주제 | 참조 |
|---|---|
| 음악 생성 | 음악 생성 |
| 음악 상태 가져오기 | 음악 상태 가져오기 |
| 작업 상태 가져오기 | 작업 상태 가져오기 |
| 모델 목록 | 모델 목록 |
| 청구 및 가격 | 청구 및 가격 |