API cover từ clip nguồn

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

Mô tả endpoint

Cover từ clip nguồn tái sử dụng một clip nguồn bạn đã tải lên, hoặc đã có sẵn, và tạo ra một phiên bản cover mới dựa trên nó.

Endpoint: POST /api/music/generate-from-source

Tính phí: Có phí, hiện mặc định 0,6 ¥ mỗi lần gọi. Việc tải âm thanh nguồn lên không tính phí; phí phát sinh khi bạn tạo cover từ clip nguồn. Số tiền thực trừ tuân theo cấu hình giá hiện tại 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 (0,6 → 1,2 ¥ mỗi lần); 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.

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.

Cách dùng được khuyến nghị: đây là bước 2 của «cover hai bước». Ở bước 1, hãy tải lên bằng API tải lên âm thanh nguồn (miễn phí) và giữ lại clip_id; ở bước 2, gọi endpoint này để bắt đầu cover. Như vậy âm thanh chỉ xuất hiện ở bước miễn phí: nếu tải lên hỏng thì cứ thử lại, không bị trừ tiền, còn phần thân yêu cầu của bước tính phí chỉ vài trăm byte, nên gần như không thể thất bại vì đường truyền bị cắt. API tải lên và cover trong một bước đặt toàn bộ âm thanh vào phần thân yêu cầu, nên khi âm thanh vượt khoảng 8 MB thì dễ bị cắt cụt trên đường truyền và trả về unexpected end of JSON input (xem "Tệp lớn và yêu cầu bị cắt" ở trang đó).

Ngoài ra, cùng một clip_id có thể dùng lại cho Extend, Replace Section, tách nhạc cụ và các thao tác tiếp theo khác, không cần tải âm thanh lên lần nữa.

Tham số yêu cầu

Headers

Tham số body

weirdnessConstraint, styleWeight và audio_weight đều nhận số thập phân tỉ lệ từ 0.0 đến 1.0, không phải số nguyên phần trăm; ví dụ 50% thì ghi 0.5. 0 là giá trị hợp lệ; chỉ khi bỏ hẳn trường mới nghĩa là "không chỉ định". audio_weight được ánh xạ tới metadata.control_sliders.audio_weight của Suno và điều khiển mức mà kết quả dựa vào âm thanh tham chiếu; chỉ được gửi kèm khi yêu cầu có sourceClipId hợp lệ hoặc âm thanh tham chiếu, nên đừng gửi trong trường hợp tạo nhạc chỉ có văn bản thông thường. Khi customMode=true, hãy ghi lời mới vào prompt và cung cấp đồng thời style và title; khi customMode=false, hãy ghi mô tả sáng tác vào prompt. instrumental và waitAudio phải dùng giá trị boolean JSON true/false.

Endpoint này mặc định trả về bất đồng bộ. Khi status trả về là pending thì audio_url rỗng là bình thường; hãy chờ hoàn tất rồi mới dùng địa chỉ âm thanh. sourceClipId phải là ID bài hát/clip nguồn thật, không được dùng task_id, client_request_id hay ID giữ chỗ pending:.

sourceClipId là ID gì

sourceClipId là định danh clip Suno thật được dùng làm nguồn cho lần cover này. Đối tượng bài hát phía khách hàng của nền tảng thường gọi định danh này là song_id, còn tham số yêu cầu cover vẫn giữ tên sourceClipId; ở đây cả hai cùng chỉ một ID bài hát thật.

Nếu nguồn là tải lên tăng cường, hãy truy vấn tác vụ tải lên tăng cường trước, chờ status chuyển thành completed, rồi đặt song_id thật trả về vào sourceClipId. Nên đặt thêm audio_url và title của kết quả đó vào sourceAudioUrl và sourceTitle.

Đừng đặt task_id, client_request_id hay ID giữ chỗ pending:enhanced-upload:* của tải lên tăng cường vào sourceClipId.

Ví dụ yêu cầu

curl -X POST https://www.suno-api.io/api/music/generate-from-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "sourceClipId": "uploaded_or_existing_clip_id",
    "sourceAudioUrl": "https://example.com/source.mp3",
    "sourceTitle": "Tiêu đề âm thanh gốc",
    "prompt": "Lời mới hoặc hướng sáng tác",
    "customMode": true,
    "style": "Mandopop, warm vocal",
    "title": "Tiêu đề cover",
    "negativeTags": "noise",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false
  }'

Phản hồi

{
  "code": 200,
  "message": "success",
  "data": {
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Tiêu đề cover",
        "status": "pending"
      }
    ],
    "source_update": {}
  }
}

Lưu ý

Endpoint này cố gắng xử lý vấn đề clip nguồn thuộc tài khoản nào. Nếu clip nguồn không dùng được trực tiếp, máy chủ có thể tải lại nó dựa trên thông tin âm thanh nguồn rồi mới tạo.