API tải lên và cover trong một bước

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

Mô tả endpoint

Tải lên và cover trong một bước gửi một tệp âm thanh hoặc URL âm thanh và tạo ra phiên bản cover mới từ âm thanh nguồn đó.

Endpoint: POST /api/music/upload-cover

Tính phí: Có phí, hiện mặc định 0,6 ¥ mỗi lần gọi. Endpoint này là "tải lên rồi cover", không phải tải lên ảnh bìa. 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.

Khi âm thanh lớn, nên tách "tải lên" và "cover" thành hai bước (khuyến nghị)

Endpoint này yêu cầu đưa toàn bộ âm thanh vào phần thân yêu cầu: âm thanh càng lớn thì phần thân càng lớn, và chỉ một lần mạng chập chờn hay timeout là cắt ngang đường truyền, sau đó máy chủ trả về unexpected end of JSON input (HTTP 400, không tính phí).

Khi âm thanh vượt khoảng 8 MB, mạng không ổn định hoặc cùng một tư liệu nguồn sẽ được dùng lại, hãy chuyển sang dạng hai bước:

1. POST /api/music/upload-source tải âm thanh nguồn lên trước — miễn phí, có thể thử lại bất cứ lúc nào — và trả về clip_id;
2. POST /api/music/generate-from-source dùng clip_id đó để bắt đầu cover — phần thân của bước tính phí chỉ khoảng 250 byte.

Xem API tải lên âm thanh nguồn, API cover từ clip nguồn và "Tệp lớn và yêu cầu bị cắt" ở cuối trang này.

Tham số yêu cầu

Headers

Tham số body

cover_start_s và cover_end_s tính bằng giây và có thể là số thập phân; thời điểm bắt đầu phải nhỏ hơn thời điểm kết thúc và không được vượt quá độ dài âm thanh nguồn. Nếu bỏ cả hai trường thì dùng toàn bộ âm thanh. 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; nhận giá trị 0.0-1.0 và chỉ được gửi kèm khi yêu cầu có âm thanh tham chiếu hợp lệ trong file_url hoặc file_base64. 0 là giá trị hợp lệ; bỏ trường nghĩa là "không chỉ định" và giữ hành vi mặc định của Suno. instrumental và waitAudio phải là boolean JSON, không phải chuỗi.

Endpoint tải lên mặc định trả về bất đồng bộ. Khi clips[].status trong phản hồi là pending thì audio_url rỗng là bình thường và không có nghĩa là tải lên hay cover đã thất bại; hãy lưu song_id thật được trả về và gọi endpoint truy vấn bài hát cho đến khi hoàn tất rồi mới đọc địa chỉ âm thanh.

Ví dụ yêu cầu

curl -X POST https://www.suno-api.io/api/music/upload-cover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "prompt": "Lời mới hoặc hướng chuyển thể",
    "style": "Mandopop, acoustic guitar",
    "title": "Bản cover",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

Phản hồi

{
  "code": 200,
  "message": "success",
  "data": {
    "upload": {
      "clip_id": "uploaded_clip_id",
      "status": "complete"
    },
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Bản cover",
        "status": "pending"
      }
    ]
  }
}

Tệp lớn và yêu cầu bị cắt

Khuyến nghị: tách tải lên và cover thành hai bước

Endpoint làm một lần (endpoint này) gộp tải lên và tạo nhạc vào một bước: phần thân lớn nằm ở bước duy nhất đó, nên khi bị cắt bạn không biết có tạo được gì hay không và cũng khó biết có bị tính phí hay không.

Kết luận: âm thanh trên khoảng 8 MB, mạng không ổn định hoặc cùng một tư liệu dùng nhiều lần → dùng dạng hai bước; âm thanh rất nhỏ và mạng ổn định → endpoint này tiện hơn.

400 unexpected end of JSON input nghĩa là gì

Nghĩa là JSON mà máy chủ nhận được không đầy đủ (không phải sai tham số, cũng không phải vấn đề quyền hay số dư). Các nguyên nhân thường gặp, xếp theo mức độ khả dĩ:

1. Phần thân lớn bị cắt giữa đường truyền: tầng vào ghi lại cả "client khai báo gửi bao nhiêu byte" và "thực tế nhận được bao nhiêu". Trường hợp đo được: client khai 14,17 MB nhưng chỉ nhận 11,8–12,4 MB, và cả ba yêu cầu đều dừng ở khoảng 1,6–1,7 giây; số byte thiếu mỗi lần một khác, cho thấy đứt đường truyền chứ không phải giới hạn cố định (máy chủ không giới hạn kích thước phần thân).
2. Content-Length không khớp với số byte thực gửi: trong Node.js, dùng .length của chuỗi (số ký tự UTF-16) làm độ dài sẽ tính sai khi nội dung có tiếng Trung hoặc văn bản nhiều byte khác.
3. Ghi phần thân bằng chuỗi thay vì Buffer, nên số byte ghi ra không khớp với khai báo.

Cả ba trường hợp đều xảy ra trước khi tính phí, nên không phát sinh chi phí.

Danh sách tự kiểm tra phía client

• Content-Length lấy từ Buffer.byteLength(json, 'utf8') (hoặc Buffer.from(json).length) — không dùng json.length;
• Phần thân yêu cầu ghi bằng Buffer, không ghi bằng chuỗi;
• Timeout socket / yêu cầu ≥ 300 giây;
• Khi âm thanh lớn hơn khoảng 8 MB: dùng file_url (phần thân chỉ vài trăm byte), hoặc dùng tải lên multipart của upload-source, hoặc chuyển thẳng sang dạng hai bước;
• Với yêu cầu multipart, không tự đặt Content-Type (để client tự thêm boundary);
• In ra "số byte thực gửi" và so với Content-Length;
• Ở dạng hai bước, xác nhận bước 1 đã trả về clip_id với status hoàn tất rồi mới gửi bước 2.

Lỗi thường gặp

Endpoint liên quan: API tải lên âm thanh nguồn (bước 1), API cover từ clip nguồn (bước 2).