TokenLab

Âm nhạc

Tạo nhạc

Tạo tác vụ tạo nhạc, lời bài hát hoặc âm thanh

POST
/v1/music/generations

Sử dụng GET /v1/models?recommended_for=music để lấy danh sách các model âm nhạc hiện tại.

Tạo nhạc, lời bài hát và âm thanh bằng AI. Đây là một API bất đồng bộ. Phản hồi tạo tác vụ sẽ trả về một định danh tác vụ. Thực hiện poll GET /v1/tasks/{id} với định danh này để theo dõi trạng thái.

Các model khác nhau về các trường dữ liệu mà chúng chấp nhận. Hãy kiểm tra GET /v1/models/{model} trước khi gửi các trường tùy chọn; trường mà model không liệt kê có thể trả về lỗi 400 unsupported_parameter. Các trường Suno (mv, title, tags, negative_tags, audio_operation và các trường đi kèm) áp dụng cho các model Suno. user không được hỗ trợ và sẽ trả về lỗi 400.

Thân yêu cầu

modelstringmặc định: suno-music

ID của model âm nhạc, chẳng hạn như suno-music hoặc stable-audio-3. Hãy gửi giá trị này một cách rõ ràng. Nếu chỉ tạo lời bài hát, hãy chọn model có các thao tác công khai hiện tại bao gồm lyrics.

promptstring

Mô tả âm nhạc hoặc văn bản thay thế. Bắt buộc đối với music, lyrics, upload-cover, upload-extend và replace-section; tùy chọn đối với add-instrumental và tách stem.

titlestring

Tiêu đề cho bài hát được tạo.

tagsstring

Các thẻ thể loại (ví dụ: "pop, upbeat, electronic").

negative_tagsstring

Các phong cách cần tránh. Bắt buộc khi audio_operation là add-instrumental.

actionstring

Giá trị MUSIC hoặc LYRICS tùy chọn. Chọn model hỗ trợ thao tác công khai tương ứng; trường này không thêm hỗ trợ lời bài hát cho model chỉ dành cho âm nhạc.

mvstring

Bộ chọn phiên bản Suno. Bắt buộc đối với generation, upload-cover, upload-extend, add-instrumental và thay thế từ audio_url. Bỏ qua trường này đối với lyrics, thay thế từ task_id + audio_id và tách stem. Các giá trị được chấp nhận: chirp-v6, chirp-v6-mini, chirp-v6-wild.

make_instrumentalboolean

Đặt thành true để tạo bản nhạc không lời (instrumental) không có giọng hát.

audio_urlstring

URL âm thanh tham chiếu có thể truy cập công khai hoặc đã tải lên. Khi được cung cấp mà không có audio_operation, TokenLab sẽ sử dụng luồng upload-cover.

audio_operationstring

Thao tác âm thanh: upload-cover, upload-extend, add-instrumental, replace-section, vocal-separate, multi-stem-separation, advanced-split.

vocal-separate, multi-stem-separation và advanced-split yêu cầu task_id + audio_id; advanced-split cũng yêu cầu stem_name. upload-extend yêu cầu continue_at lớn hơn 0. add-instrumental yêu cầu audio_url, title, tags và negative_tags.

Đối với replace-section, hãy gửi prompt, tags, title, infill_start_s, infill_end_s và full_lyrics. Chọn chính xác một nguồn: task_id + audio_id, hoặc audio_url + mv. Khoảng thời gian thay thế phải từ 6–60 giây.

task_idstring

ID tác vụ nguồn thuộc tổ chức của bạn, dùng để thay thế âm thanh đã tạo hoặc tách stem.

audio_idstring

ID âm thanh nguồn được trả về trong kết quả tác vụ nguồn. Bắt buộc cùng với task_id để thay thế âm thanh đã tạo và tách stem.

infill_start_snumber

Thời gian bắt đầu thay thế tính bằng giây, tối thiểu là 0. Bắt buộc đối với replace-section.

infill_end_snumber

Thời gian kết thúc thay thế tính bằng giây. Bắt buộc đối với replace-section; phải sau infill_start_s từ 6–60 giây.

full_lyricsstring

Toàn bộ lời bài hát cho bài hát đầu ra. Bắt buộc đối với replace-section.

stem_namestring

Tên stem. Bắt buộc đối với advanced-split.

continue_clip_idstring

ID của clip trước đó để tiếp tục.

continue_atnumber

Thời gian tính bằng giây để tiếp tục. Bắt buộc và phải lớn hơn 0 đối với upload-extend.

durationinteger

Độ dài của âm thanh được tạo tính bằng giây, từ 1 đến 380. Chỉ dành cho các model liệt kê trường này, chẳng hạn như stable-audio-3; chi tiết của model sẽ cung cấp giới hạn riêng của model đó.

output_formatstring

Định dạng tệp âm thanh được liệt kê bởi model, ví dụ: mp3, wav, hoặc flac. Chỉ áp dụng cho các model có liệt kê định dạng này.

seedinteger

Seed để tái lập kết quả đầu ra, từ 0 đến 4294967294. Chỉ dành cho các model liệt kê trường này.

stepsinteger

Số lượng bước tạo. Phạm vi phụ thuộc vào từng model (ví dụ: từ 4 đến 8 đối với stable-audio-3). Chỉ áp dụng cho các model có liệt kê tham số này.

Một số model liệt kê nhiều trường hơn, chẳng hạn như negative_prompt, n, seconds và guidance_scale. Chỉ gửi các trường này khi thông tin chi tiết của model có liệt kê chúng; một trường mà model đã chọn không hỗ trợ sẽ trả về lỗi 400.

cfg_scalenumber

Độ mạnh hướng dẫn theo prompt (prompt guidance strength), từ 1 đến 25. Chỉ dành cho các model liệt kê trường này.

prompt chấp nhận tối đa 5000 ký tự; tags và negative_tags chấp nhận tối đa 1000 ký tự cho mỗi trường. Các thao tác và tham số được hỗ trợ phụ thuộc vào chi tiết hiện tại của model đã chọn.

Phản hồi

idstring

ID tác vụ để poll trạng thái.

task_idstring

Bí danh của cùng một ID tác vụ bất đồng bộ, khi được trả về.

poll_urlstring

URL trạng thái cho tác vụ này. Thực hiện poll GET /v1/tasks/{id} với id.

statusstring

Trạng thái tác vụ: pending, processing, completed hoặc failed.

createdinteger

Thời gian tạo tác vụ dưới dạng Unix timestamp, khi được trả về.

Yêu cầu

curl -X POST "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 electronic dance track with heavy bass",
    "title": "Night Drive",
    "tags": "electronic, EDM, energetic"
  }'

Ví dụ tạo âm thanh cho model nhận duration và output_format thay vì các trường Suno:

{
  "model": "stable-audio-3",
  "prompt": "Warm lo-fi beat with soft vinyl crackle",
  "duration": 30,
  "output_format": "mp3"
}

Phản hồi

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "suno-music"
}

Xác thực

BearerAuth
AuthorizationBearer <token>

Xác thực bằng Khóa API. Tạo hoặc quản lý khóa API trong Dashboard > API > API Keys.

Vị trí: header

Header

X-TokenLab-Delivery-Policy?string

Chính sách phân phối theo yêu cầu. Ghi đè các mặc định của API key và Workspace. Tự động thử TokenLab Verified trước và có thể chuyển đổi một lần sang Official chỉ trước khi xuất, chấp nhận yêu cầu hoặc tạo tài nguyên cố định.

Giá trị hợp lệ

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Khóa tùy chọn giúp yêu cầu tạo trở nên an toàn khi thử lại. Hãy gửi một giá trị duy nhất mới, chẳng hạn như UUID, cho mỗi tác vụ. Thử lại với cùng khóa và cùng phần thân sẽ trả về kết quả của yêu cầu tạo ban đầu, thường là tác vụ gốc, và không tạo, điều phối hoặc tính phí tác vụ thứ hai. Phần thân khác với khóa đã được chấp nhận sẽ bị từ chối với 409. Khóa dài hơn 255 ký tự sẽ bị bỏ qua và yêu cầu đó sẽ không có bảo vệ idempotency. Xem Thử lại an toàn với khóa idempotency.

Độ dài1 <= length <= 255

Nội dung yêu cầu

application/json

Phản hồi

application/json

application/json

application/json

application/json

application/json

application/json