API thêm giọng hát

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

Mô tả endpoint

Thêm giọng hát giúp tạo, viết lại hoặc bổ sung phần vocal trên một bài hát đã có hoặc trên nguồn nhạc không lời.

Endpoint: POST /api/music/add-vocal

Tính phí: Có phí, tính theo mô hình được yêu cầu; số tiền thực trừ tuân theo cấu hình giá trong phần quản trị.

Max Mode / Variety: endpoint này hỗ trợ hai tham số tùy chọn max_mode và variety (0-4). Khi bật max_mode, lần gọi này bị tính gấp đôi; variety không phát sinh phí thêm. Ý nghĩa và cách gửi xem mục "Tham số nâng cao" trong Tổng quan API mới.

Mô hình đề xuất: suno-v6. Có thể dùng suno-v6, suno-v6-wild hoặc suno-v6-mini.

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í dụ yêu cầu

curl -X POST https://www.suno-api.io/api/music/add-vocal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "source_clip_id": "source_song_id",
    "lyrics": "[Verse]\nĐêm buông ngoài khung cửa\n[Chorus]\nTa bước về phía ánh sáng",
    "style_tags": "warm male vocal, mandopop, intimate",
    "song_title": "Bản tăng cường giọng hát",
    "instrumental": false,
    "wait_completion": false
  }'

Phản hồi

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "result_song_id",
        "song_title": "Bản tăng cường giọng hát",
        "status": "pending"
      },
      {
        "song_id": "result_song_id_2",
        "song_title": "Bản tăng cường giọng hát",
        "status": "pending"
      }
    ]
  }
}

Một lần gọi trả về 2 kết quả (tính phí như 2 bài); ví dụ hiển thị 2. Hãy căn theo độ dài mảng clips và đừng viết vòng lặp cố định số lần. Lưu clips[].song_id rồi dùng API truy vấn bài hát và lịch sử để hỏi cho đến khi completed.

Lưu ý

• Thêm giọng hát nghĩa là "tạo hoặc viết lại phần vocal trên bài hát nguồn"; không giống với tùy chọn vocal_gender.
• Cần dùng giọng đã clone thì dùng 【Khuyến nghị】 API hồ sơ giọng nói; API nhân bản giọng nói và tạo nhạc với giọng chỉ định (chuỗi cũ) không được khuyến nghị cho tích hợp mới.