API tách track (giọng hát và nhạc đệm)

Cập nhật 2026-09-18 · nhóm Suno-API

Mô tả endpoint

Tách track chia một bài hát có sẵn thành giọng hát, nhạc đệm hoặc kết quả nhiều track. Quy trình tích hợp được khuyến nghị:

1. Nếu âm thanh nguồn không phải bài hát do nền tảng này tạo ra, hãy gọi API tải lên âm thanh nguồn trước.
2. Gọi POST /api/music/separate để gửi tác vụ tách track.
3. Dùng API truy vấn bài hát và lịch sử để hỏi kết quả.
4. Dùng các endpoint tải xuống để tải tệp âm thanh của từng kết quả tách.

Endpoint: POST /api/music/separate

Tính phí: Có phí. stem_mode=two hiện mặc định 0,6 ¥ mỗi lần gọi; stem_mode=twelve là tách nhiều track, hiện mặc định 3,0 ¥ mỗi lần gọi. Số tiền thực trừ tuân theo cấu hình giá trong phần quản trị.

Thời gian chờ và timeout (quan trọng): đây là endpoint đồng bộ — đơn chỉ được tiếp nhận và đưa vào tạo nhạc khi phản hồi trả về. Theo đo đạc, phần lớn yêu cầu trả về trong 1-3 giây, khoảng 10% mất hơn 30 giây và lâu nhất khoảng 230 giây. Hãy đặt timeout phía client từ 300 giây trở lên; không nhận được phản hồi không có nghĩa là chưa tạo gì, và đừng thử lại ngay sau khi timeout (sẽ trùng đơn và bị tính phí hai lần). Nếu kết nối bị ngắt, hãy kiểm tra lại sau bằng GET /api/music/songs. Xem "Thời gian chờ và thiết lập timeout" trong Tổng quan API mới.

Xác thực

Tham số yêu cầu

Về stem_mode

Về việc tách track

Tách track là một khả năng cố định độc lập: không cần điền hay chọn model tạo nhạc. Khách hàng chỉ gửi bài hát nguồn và stem_mode; máy chủ xử lý theo chế độ.

Số mục từ đâu ra: một lần gửi tạo 2 phiên bản (hai kết quả từ cùng một tư liệu), nên số mục = 2 × số track của chế độ đó: two là 4, twelve là 24. Hãy luôn dựa vào độ dài thực tế của mảng clips trong phản hồi; đừng viết vòng lặp theo số cố định (một số track có thể thất bại, các track thành công vẫn được trả về bình thường).

Mỗi chế độ trả về những track nào

12 track của chế độ twelve (tên do nền tảng đặt cố định; thứ tự có thể thay đổi):

Chế độ two trả về hai track, (Vocals) và (Instrumental), mỗi track 2 phiên bản. Tên track của two và twelve đều là tên cố định (không kèm tên bài hát nguồn), nên đừng mong nhìn tên mà biết là bài nào.

Không thể dùng tên track làm khoá duy nhất. Trong hai phiên bản sẽ có track trùng tên (ví dụ hai (Vocals), hai (Strings)), và một lần tách trả về nhiều track. Hãy luôn dùng song_id làm định danh, song_title chỉ để hiển thị; cũng đừng dùng chỉ số mảng (thứ tự có thể thay đổi).

Ví dụ yêu cầu

Tách giọng hát / nhạc đệm (stem_mode: "two")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "two",
    "source_audio_url": "https://example.com/source.mp3",
    "source_file_name": "source.mp3",
    "source_title": "Source Song"
  }'

Tách nhiều track (stem_mode: "twelve")

curl -X POST https://www.suno-api.io/api/music/separate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "source_clip_id",
    "stem_mode": "twelve",
    "source_audio_url": "https://example.com/source.mp3"
  }'

Phản hồi

Khi thành công thường trả về một mảng kết quả tách. Mỗi kết quả là một clip bài hát độc lập và cần tiếp tục truy vấn cho đến khi status chuyển sang trạng thái hoàn tất.

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "stem_clip_id_1",
        "song_title": "(Vocals)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      },
      {
        "song_id": "stem_clip_id_2",
        "song_title": "(Instrumental)",
        "status": "pending",
        "generation_type": "separate",
        "created_at": "2026-06-06T10:00:00Z"
      }
    ]
  }
}

Ở trên chỉ hiển thị 2 trong 4 mục của chế độ two; thực tế trả về 4 (2 phiên bản × {(Vocals), (Instrumental)}); chế độ twelve trả về 24. Số thực tế là độ dài mảng clips.

Khách hàng thường chỉ cần lưu clips[].song_id; các truy vấn và tải xuống sau đó đều xoay quanh những ID này.

Lưu ý

• Kết quả tách không xuất hiện trong lịch sử GET /api/music/songs (danh sách đó chỉ trả về các bài hát được tạo thông thường). Sau khi gửi thành công hãy lưu ngay clips[].song_id, nếu không sau này sẽ không tìm được.
• Mỗi track là một tác phẩm độc lập: mỗi track có song_id riêng, cần truy vấn riêng đến khi xong và tải riêng.
• Tính phí không liên quan đến số mục: tính theo lần gọi (two 0,6 ¥ mỗi lần, twelve 3,0 ¥ mỗi lần), 4 hay 24 mục đều cùng giá.
• Tải xuống: dùng song_id của track đó với POST /api/music/download-url / download-file (miễn phí), hoặc dùng thẳng audio_url trong kết quả truy vấn; lấy MIDI xem API lấy MIDI.
• Đừng gửi hai lần: tách track là endpoint đồng bộ, nên sau khi timeout hãy kiểm tra bằng truy vấn bài hát trước, đừng thử lại ngay (sẽ trùng đơn và bị tính phí hai lần).
• Ẩn những track không cần nữa bằng API xoá stem.

Truy vấn kết quả tách

Sau khi gửi thành công, dùng clips[].song_id gọi POST /api/music/query để truy vấn kết quả.

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_ids": "stem_clip_id_1,stem_clip_id_2"
  }'

Ví dụ truy vấn đã hoàn tất:

[
  {
    "song_id": "stem_clip_id_1",
    "song_title": "(Vocals)",
    "status": "complete",
    "audio_url": "https://...",
    "cover_url": "https://...",
    "duration": 180.5,
    "generation_type": "separate",
    "stem_from_id": "source_clip_id"
  }
]

Tải tệp track

Khi kết quả tách đã xong, bạn có thể tải một tệp track riêng bằng endpoint tải xuống.

Endpoint: POST /api/music/download-file

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1",
    "kind": "audio"
  }' \
  --output stem.mp3

kind hỗ trợ:

Muốn đóng gói tài nguyên liên quan của một kết quả tách, hãy gọi:

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "stem_clip_id_1"
  }' \
  --output stem-resources.zip

Giải thích trạng thái

Lỗi thường gặp

Ghi chú tương thích

Tài liệu cũ từng dùng ví dụ một đối tượng như success/task_id/vocals_url/instrumental_url. Tách track hiện tại dựa trên mảng bài hát clips[]: mỗi kết quả tách có song_id riêng, và các truy vấn, tải xuống sau đó đều xoay quanh những song_id này.

Trang liên quan

• Nếu chỉ cần tách giọng hát và nhạc đệm mà không cần chọn chế độ, hãy dùng API xóa giọng hát; đây là dạng nhanh hai track của endpoint này và hiện miễn phí.
• Ẩn những track không cần nữa bằng API xoá stem (xoá mềm, không tính phí).
• Lấy MIDI của track xem API lấy MIDI; lấy âm thanh, ảnh bìa và media khác xem API tải và nghe thử media của bài hát.