TokenLab

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ạoCác trường chínhGhi chú
Bài hát đầy đủ hoặc nhạc không lờimodel, 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átmodel, 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_atGiữ nguyên ID của clip trước đó
Cover hoặc mở rộng âm thanh của riêng bạnmodel, mv, prompt, audio_url, tùy chọn audio_operationaudio_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-splitMỗ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 được completed hoặc failed.
  • 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 completed và 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ứngNguyên nhân có thểCách khắc phục
Tác vụ đã tạo nhưng không có trình phátTác vụ vẫn đang chờ hoặc đã hoàn thành mà không có audio_urlTiế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ớiGiao diện người dùng đã tạo lại tác vụ thay vì tiếp tụcLưu trữ và sử dụng lại task_id
Tác vụ lời bài hát không trả về âm thanhaction: "LYRICS" chỉ dành cho văn bảnTá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ạcTạo nhạc
Nhận trạng thái nhạcNhậ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 modelLiệt kê các model
Thanh toán & Giá cảThanh toán & Giá cả

Trên trang này