Hướng dẫn media
Tạo nhạc
Tạo bài hát hoặc lời bài hát và chờ đợi âm thanh hoàn thiện
Việc tạo nhạc diễn ra theo cơ chế bất đồng bộ. POST /v1/music/generations trả về một ID tác vụ, trạng thái và thường là poll_url. Hãy thực hiện GET /v1/tasks/{id} với ID đó cho đến khi tác vụ ở trạng thái completed (hoàn thành) hoặc failed (thất bại).
Chọn nội dung cần tạo
| Nội dung cần tạo | Các trường chính | Ghi chú |
|---|---|---|
| Bài hát đầy đủ hoặc nhạc không lời | model, mv, prompt, tùy chọn title, tags, action: "MUSIC" | Sử dụng khi người dùng mong đợi âm thanh cuối cùng |
| Chỉ lời bài hát | model, prompt, action: "LYRICS" | Chỉ sử dụng với các model hỗ trợ tạo lời bài hát |
| Tiếp tục một đoạn clip hiện có | model, mv, prompt, continue_clip_id, tùy chọn continue_at | Giữ nguyên ID của clip trước đó |
| Cover hoặc mở rộng âm thanh của riêng bạn | model, mv, prompt, audio_url, tùy chọn audio_operation | audio_url phải là URL công khai. audio_operation mặc định là upload-cover; upload-extend cũng cần continue_at |
| Thêm nhạc đệm, thay thế một phần hoặc tách các thành phần (stems) | audio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation, hoặc advanced-split | Mỗi thao tác có các trường bắt buộc riêng; xem Tạo nhạc |
Lấy danh sách model âm nhạc hiện tại từ:
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
-H "Authorization: Bearer sk-your-api-key"Ví dụ dưới đây sử dụng suno-music với mv: "chirp-v6". Các model âm nhạc khác, chẳng hạn như stable-audio-3, sử dụng các trường khác như duration và output_format; hãy đọc chi tiết của model trước. Đối với chỉ lời bài hát, hãy chọn một model có tài liệu về tạo lời, gửi action: "LYRICS" và bỏ qua mv.
Tạo một tác vụ âm nhạc
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"
}'Các prompt, tiêu đề và thẻ có thể xuất hiện trong lịch sử sản phẩm của bạn. Không bao giờ đặt khóa API, URL riêng tư hoặc dữ liệu chẩn đoán vào các trường này.
Nhận âm thanh hoàn thiện
Gọi GET /v1/tasks/{id} với id hoặc task_id đã trả về.
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Cấu trúc phản hồi
Phản hồi tạo tác vụ là một bản ghi tác vụ, không phải âm thanh cuối cùng:
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"created": 1706000000,
"model": "suno-music"
}Một phản hồi polling đã hoàn tất có thể bao gồm các trường phương tiện cuối cùng:
{
"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"
}
]
}
}Các trường phương tiện cuối cùng sẽ không xuất hiện cho đến khi status là completed. Các tác vụ thất bại sẽ trả về status: "failed" kèm theo error.
Các trạng thái bao gồm pending, processing, completed và failed. Một tác vụ đã hoàn thành có thể bao gồm audio_url, video_url, title, lyrics và các siêu dữ liệu khác. Các URL phương tiện là các URL của TokenLab có hiệu lực trong 30 ngày; hãy tải xuống hoặc lưu lại kết quả nếu bạn cần sử dụng lâu hơn.
Hiển thị trạng thái phù hợp
- Hiển thị trạng thái đang chờ (pending) ngay sau khi tạo tác vụ.
- Thực hiện polling mỗi
5-10 giâyđối với các tác vụ dài, sau đó dừng lại khi nhận đượccompletedhoặcfailed. - Không hiển thị trình phát nhạc cuối cùng cho đến khi tác vụ ở trạng thái
completedvàaudio_urlđã tồn tại. - Đối với các tác vụ chỉ tạo lời bài hát, hãy hiển thị đầu ra văn bản tách biệt với các tác vụ âm thanh để người dùng hiểu rõ những gì họ đang nhận được.
- Khi làm mới trang, hãy tiếp tục từ
task_idđã lưu thay vì tạo một tác vụ mới.
Bản ghi thanh toán
Các tác vụ âm nhạc có thể dự trữ một khoản phí ước tính khi được tạo. Số tiền cuối cùng sẽ được ghi lại sau khi hoàn thành hoặc thất bại. Hãy lưu lại request_id, task_id, model, endpoint và billing_transaction_id khi chúng xuất hiện; sử dụng các bản ghi sử dụng của Management API để tính phí cuối cùng.
Các lỗi thường gặp
| Triệu chứng | Nguyên nhân có thể | Cách khắc phục |
|---|---|---|
| Tác vụ đã tạo nhưng không có trình phát | Tác vụ vẫn đang chờ hoặc đã hoàn thành mà không có audio_url | Tiếp tục polling cho đến khi kết thúc, sau đó xử lý việc thiếu đầu ra như một công việc thất bại của người dùng |
| Bài hát bị trùng lặp sau khi làm mới | Giao diện người dùng đã tạo lại tác vụ thay vì tiếp tục | Lưu trữ và sử dụng lại task_id |
| Tác vụ lời bài hát không trả về âm thanh | action: "LYRICS" chỉ dành cho văn bản | Tách biệt các luồng giao diện người dùng cho lời bài hát và âm nhạc |
| Tham số không được hỗ trợ | Model đã chọn không chấp nhận trường đó | Xóa trường đó hoặc chọn một model có hỗ trợ trường đó |
Tham chiếu API
| Chủ đề | Tham chiếu |
|---|---|
| Tạo nhạc | Tạo nhạc |
| Nhận trạng thái nhạc | Nhận trạng thái nhạc |
| Nhận trạng thái tác vụ | Nhận trạng thái tác vụ |
| Liệt kê các model | Liệt kê các model |
| Thanh toán & Giá cả | Thanh toán & Giá cả |