Tạo Nhạc

Việc tạo nhạc là không đồng bộ. POST /v1/music/generations tạo một tác vụ TokenLab công khai và trả về id / task_id, status, và thường là poll_url. Ứng dụng của bạn nên lưu trữ danh tính tác vụ đó, hiển thị tiến trình và kiểm tra cho đến khi có trạng thái cuối cùng.

Chọn Quy Trình

Quy trình	Trường chính	Ghi chú
Bài hát hoàn chỉnh hoặc nhạc cụ	`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 mô hình có khả năng tạo lời bài hát
Tiếp tục một clip hiện có	`continue_clip_id`, tùy chọn `continue_at`	Lưu trữ danh tính clip/tác vụ công khai trước đó trước khi cung cấp tiếp tục

Truy vấn danh mục mô hình hiện tại trước khi gửi một danh sách mô hình mã cứng:

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

Các ví dụ công khai hiện tại sử dụng suno_music cho việc tạo nhạc và bao gồm mv với phiên bản mô hình Suno chính thức như chirp-v4. Đối với các quy trình chỉ lời bài hát, gửi action: "LYRICS" với một mô hình mà chi tiết model của nó tài liệu hóa việc tạo lời bài hát và bỏ qua mv. Xem ID mô hình là ID TokenLab công khai, không phải là đảm bảo rằng các trường cụ thể của nhà cung cấp là trường chi tiết model.

Tạo Một Tác Vụ 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-v4",
    "prompt": "Một bản nhạc synth-pop vui tươi với giọng hát ấm áp và điệp khúc trong trẻo",
    "title": "Morning Static",
    "tags": "synth-pop, vui tươi",
    "action": "MUSIC"
  }'

Giữ cho các prompt, tiêu đề và thẻ hiển thị với người dùng và an toàn để lưu trữ. Không đặt API keys, URL riêng tư hoặc thông tin chẩn đoán riêng tư vào bất kỳ trường prompt nào.

Kiểm Tra Để Hoàn Thành

Sử dụng poll_url trước. Nếu khách hàng của bạn cần một tuyến đường cố định, 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"

Dạng phản hồi

Phản hồi tạo là một bản ghi tác vụ có thể polling, 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"
}

Phản hồi polling đã hoàn tất có thể bao gồm các trường media cuối cùng:

{
  "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..."
}

Các trường media cuối cùng sẽ vắng mặt cho đến khi status là completed. Tác vụ thất bại trả về status: "failed" cùng với error. Các trạng thái công khai mong đợi là pending, processing, completed, và failed. Một tác vụ nhạc đã hoàn thành có thể bao gồm audio_url, video_url, title, lyrics, và metadata đã chuẩn hóa. Lưu trữ các URL cuối cùng trong cơ sở dữ liệu của riêng bạn để người dùng có thể mở lại kết quả mà không cần khởi động lại việc tạo.

Giao Diện Người Dùng Và Xử Lý Trạng Thái

Hiển thị trạng thái đang chờ ngay sau khi tạo tác vụ.
Kiểm tra mỗi 5-10s cho các tác vụ dài, sau đó dừng lại khi completed hoặc failed.
Không hiển thị trình phát cuối cùng cho đến khi tác vụ được completed và có audio_url.
Đối với các tác vụ chỉ lời bài hát, hiển thị đầu ra văn bản riêng biệt với các tác vụ âm thanh để người dùng hiểu những gì họ đang mua.
Khi làm mới, tiếp tục từ task_id đã lưu thay vì tạo một tác vụ mới.

Thanh Toán Và Đối Chiếu

Các tác vụ nhạc có thể giữ lại một số tiền ước tính tại thời điểm tạo và thanh toán sau khi trạng thái cuối cùng được biết. Lưu trữ request_id, task_id, mô hình, điểm cuối, và billing_transaction_id khi nó xuất hiện. Sử dụng hồ sơ sử dụng API Quản lý để đối chiếu thay vì các ID tác vụ của nhà cung cấp.

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 kiểm tra cho đến khi có trạng thái cuối cùng, sau đó xử lý đầu ra thiếu như một công việc người dùng thất bại
Bài hát 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ỉ là văn bản	Tách biệt các đường dẫn UI lời bài hát và nhạc
Tham số không được hỗ trợ	Trường không có trong chi tiết model của mô hình	Xóa các trường cụ thể của nhà cung cấp hoặc chọn một mô hình tài liệu hóa chúng

Tài Liệu API

Chủ đề	Tài liệu tham khảo
Tạo Nhạc	Tạo Nhạc
Lấy Trạng Thái Nhạc	Lấy Trạng Thái Nhạc
Lấy Trạng Thái Tác Vụ	Lấy Trạng Thái Tác Vụ
Danh Sách Mô Hình	Danh Sách Mô Hình
Thanh Toán & Giá Cả	Thanh Toán & Giá Cả

Bắt đầu

Hướng dẫn cốt lõi

Hướng dẫn media

Chọn Quy Trình

Tạo Một Tác Vụ Nhạc

Kiểm Tra Để Hoàn Thành

Dạng phản hồi

Giao Diện Người Dùng Và Xử Lý Trạng Thái

Thanh Toán Và Đối Chiếu

Lỗi Thường Gặp

Tài Liệu API

​Chọn Quy Trình

​Tạo Một Tác Vụ Nhạc

​Kiểm Tra Để Hoàn Thành

​Dạng phản hồi

​Giao Diện Người Dùng Và Xử Lý Trạng Thái

​Thanh Toán Và Đối Chiếu

​Lỗi Thường Gặp

​Tài Liệu API

Chọn Quy Trình

Tạo Một Tác Vụ Nhạc

Kiểm Tra Để Hoàn Thành

Dạng phản hồi

Giao Diện Người Dùng Và Xử Lý Trạng Thái

Thanh Toán Và Đối Chiếu

Lỗi Thường Gặp

Tài Liệu API