API tải lên âm thanh nguồn

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

Mô tả endpoint

Tải lên âm thanh nguồn biến tệp âm thanh cục bộ hoặc từ xa thành clip nguồn mà các khả năng sau có thể dùng: cover, kéo dài, thay đoạn, tách track và những tính năng khác.

Endpoint: POST /api/music/upload-source

Tính phí: Miễn phí. Endpoint này chỉ tải lên âm thanh nguồn; không bắt đầu tác vụ tạo nhạc.

Cách dùng được khuyến nghị: đây là bước 1 của «cover hai bước». Trước tiên hãy tải âm thanh lên bằng endpoint này (miễn phí, thất bại có thể thử lại bất cứ lúc nào) và lưu clip_id trả về; sau khi xác nhận tải lên thành công (status ở trạng thái hoàn tất), hãy gọi API cover từ clip nguồn để bắt đầu cover — phần thân của yêu cầu đó chỉ vài trăm byte, nên không thể bị cắt khi truyền vì âm thanh quá lớn. So với API làm một lần tải lên rồi cover, cách tách này ổn định hơn khi âm thanh lớn, mạng không ổn định, hoặc cùng một tư liệu phải dùng lại nhiều lần (kéo dài / thay đoạn / tách track).

Gợi ý khi tải tệp lớn

Sau khi tải lên xong, luôn xác nhận status trong phản hồi đã ở trạng thái hoàn tất và lưu clip_id trước khi sang bước 2; tải lên thất bại không bị tính phí và không tạo tác vụ tạo nhạc, chỉ cần thử lại.

Kiểm tra file_url trước khi tải lên

Máy chủ nền tảng tự tải file_url bằng HTTP, không phải trình duyệt của bạn. URL mở được trên trình duyệt chưa chắc máy chủ sản xuất có thể truy cập.

Với tệp cục bộ, hãy dùng multipart với trường file. Không dùng file_url cho liên kết ByteDance hoặc URL có chữ ký tạm thời trừ khi URL công khai và vẫn còn hiệu lực khi gửi yêu cầu.

Chạy lệnh này từ một máy chủ công khai trước khi gửi yêu cầu tải lên:

curl -L --max-time 30 -D - -o /dev/null "https://example.com/source.mp3"

Yêu cầu GET phải kết thúc bằng HTTP 200, trả về MIME âm thanh và có dữ liệu. Trang đăng nhập, phản hồi HTML và mã 401, 403, 404 hoặc 410 đều không dùng được.

file_url download failed: HTTP 404 thường có nghĩa chữ ký đã hết hạn, tệp đã bị xóa hoặc tham số URL bị thiếu.

Tải lên này miễn phí. Nếu tải file_url thất bại, không có clip_id, tác vụ bài hát hay lệnh tạo nhạc nào được tạo và không bị tính phí; không cần hoàn tiền.

Tham số yêu cầu

Headers

Đối với yêu cầu JSON:

Không đặt Content-Type thủ công trong yêu cầu multipart; client tự tạo.

Tham số body

Ví dụ yêu cầu JSON

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -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",
    "upload_type": "file_upload"
  }'

Ví dụ yêu cầu multipart

curl -X POST https://www.suno-api.io/api/music/upload-source \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.mp3" \
  -F "file_name=source.mp3" \
  -F "upload_type=file_upload" \
  -F "model=suno-v6"

import requests

with open("source.mp3", "rb") as audio:
    response = requests.post(
        "https://www.suno-api.io/api/music/upload-source",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        data={
            "file_name": "source.mp3",
            "upload_type": "file_upload",
            "model": "suno-v6",
        },
        files={"file": ("source.mp3", audio, "audio/mpeg")},
        timeout=300,
    )

response.raise_for_status()
print(response.json())

Phản hồi

{
  "clip_id": "uploaded_clip_id",
  "status": "complete",
  "title": "source.mp3",
  "image_url": "https://...",
  "audio_url": "https://...",
  "display_tags": "pop, vocal",
  "inferred_description": "uploaded source audio",
  "clip_metadata": {}
}