API tải lên nâng cao

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

Mô tả endpoint

Tải lên nâng cao gửi một tệp âm thanh cục bộ; hệ thống thực hiện nâng cấp ở phía sau và tạo ra một bài hát hoàn chỉnh, phát được. Lệnh gửi trả về thông tin tác vụ ngay lập tức, và ứng dụng khách hỏi tiến độ qua endpoint truy vấn.

Endpoint gửi: POST /api/music/enhanced-upload

Truy vấn một tác vụ: GET /api/music/enhanced-upload/:id

Huỷ tác vụ: POST /api/music/enhanced-upload/:id/cancel

Truy vấn danh sách: GET /api/music/enhanced-upload

Tính phí: 10 ¥ mỗi lần gọi, trừ trước theo mức giá cố định của suno-enhanced-upload. Nếu tác vụ thất bại hoặc bị huỷ trong giai đoạn cho phép, khoản đã trừ trước sẽ được hoàn tự động. Số tiền thực trừ tuân theo cấu hình giá hiện tại trong phần quản trị.

Luồng gọi

1. Gọi POST /api/music/enhanced-upload để tải tệp âm thanh lên.
2. Lưu task_id được trả về.
3. Gọi GET /api/music/enhanced-upload/:id để xem tiến độ và kết quả.
4. Khi Suno hoàn tất kết xuất cuối cùng, dịch vụ dùng tài khoản Suno gắn với tác vụ đó để gọi endpoint tải xuống được uỷ quyền của Studio và ghi MP3 vào dịch vụ media CN2.
5. Tác vụ chỉ chuyển thành completed khi tài nguyên CN2 sẵn sàng; lúc đó lấy địa chỉ âm thanh CDN từ audio_url trong phản hồi.

/api/forbidden là địa chỉ giữ chỗ có thể xuất hiện trong metadata của Suno Studio; đây không phải tài nguyên phát hay tải được. Nó không bao giờ được trả cho khách hàng và không dùng làm căn cứ hoàn tất. Nếu kết xuất đã xong nhưng CN2 còn đang chuẩn bị, endpoint vẫn tiếp tục trả processing và không trả audio_url; ứng dụng khách nên tiếp tục hỏi và không coi địa chỉ rỗng là thất bại.

Gửi bản tải lên nâng cao

Headers

Tham số form

Ví dụ yêu cầu

Ví dụ dưới đây dùng cùng cách gọi như khi kiểm thử trên môi trường thật, nhưng API Key đã được thay bằng giá trị giữ chỗ.

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@source.aac" \
  -F "title=Enhanced upload demo" \
  "https://www.suno-api.io/api/music/enhanced-upload"

Phản hồi

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "title": "Enhanced upload demo",
    "file_name": "source.aac",
    "status": "queued",
    "created_at": 1781137961,
    "pre_consumed_quota": 5000000,
    "billing_source": "wallet"
  }
}

Truy vấn một tác vụ

Ví dụ yêu cầu

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209"

Ví dụ phản hồi khi đang xử lý

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "processing",
      "type": "enhanced_upload",
      "progress": {
        "stage": "media_preparing",
        "percent": 98,
        "label": "正在准备播放资源",
        "updated_at": 1781138500
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138500
    }
  }
}

Ví dụ phản hồi khi hoàn tất

{
  "success": true,
  "message": "",
  "data": {
    "task": {
      "task_id": 3209,
      "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
      "client_request_id": "cu_20260611003241723483700xnCcQg",
      "title": "Enhanced upload demo",
      "file_name": "source.aac",
      "status": "completed",
      "type": "enhanced_upload",
      "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
      "duration": 217.74,
      "progress": {
        "stage": "completed",
        "percent": 100,
        "label": "已完成",
        "updated_at": 1781138943
      },
      "pre_consumed_quota": 5000000,
      "billing_source": "wallet",
      "created_at": 1781137961,
      "updated_at": 1781138943,
      "completed_at": 1781138943
    }
  }
}

Huỷ tác vụ

Chỉ có thể huỷ khi cả tác vụ lẫn luồng xử lý phía máy chủ vẫn đang ở giai đoạn queued. Sau khi tác vụ vào leasing, running, processing hoặc đã hoàn tất thì không thể huỷ.

Ví dụ yêu cầu

curl.exe --http1.1 -s -S -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload/3209/cancel"

Phản hồi

{
  "success": true,
  "message": "",
  "data": {
    "task_id": 3209,
    "song_id": "pending:enhanced-upload:cu_20260611003241723483700xnCcQg",
    "client_request_id": "cu_20260611003241723483700xnCcQg",
    "status": "cancelled"
  }
}

Nếu tác vụ đã bắt đầu xử lý, endpoint sẽ trả về:

{
  "success": false,
  "message": "强化上传已开始处理，无法取消"
}

Truy vấn danh sách tác vụ

Endpoint danh sách chỉ trả các tác vụ tải lên nâng cao của người dùng sở hữu API Key hiện tại; tác vụ tạo nhạc thường, cover và gia hạn không bị trộn vào.

Tham số query

Ví dụ yêu cầu

curl.exe --http1.1 -s -S \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suno-api.io/api/music/enhanced-upload?p=1&page_size=3"

Phản hồi

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 3,
    "total": 1,
    "items": [
      {
        "task_id": 3209,
        "song_id": "56cbd0bb-0e8c-4a34-8729-55d5c05d9c53",
        "client_request_id": "cu_20260611003241723483700xnCcQg",
        "title": "Enhanced upload demo",
        "file_name": "source.aac",
        "status": "completed",
        "type": "enhanced_upload",
        "audio_url": "https://media.code-go.com/assets/56cbd0bb-0e8c-4a34-8729-55d5c05d9c53-mp3.mp3",
        "duration": 217.74,
        "progress": {
          "stage": "completed",
          "percent": 100,
          "label": "已完成",
          "updated_at": 1781138943
        },
        "pre_consumed_quota": 5000000,
        "billing_source": "wallet",
        "created_at": 1781137961,
        "updated_at": 1781138943,
        "completed_at": 1781138943
      }
    ]
  }
}

Giải thích các trường phản hồi

Lưu ý

• Hiện endpoint chỉ hỗ trợ tải tệp multipart; không hỗ trợ file_url hay file_base64 dạng JSON.
• Tệp tải lên tối đa 80 MB.
• Endpoint gửi là bất đồng bộ: phản hồi queued nghĩa là tác vụ đã vào hàng đợi, không có nghĩa là âm thanh đã xong.
• Huỷ chỉ áp dụng cho tác vụ chưa bắt đầu xử lý; khi đã vào giai đoạn xử lý, luồng tài khoản nền tảng không bị ngắt.
• Đừng để lộ API Key thật trong mã ứng dụng khách.

Bắt đầu cover sau khi tải lên nâng cao hoàn tất

Sau khi tải lên nâng cao hoàn tất, bạn có thể dùng kết quả làm clip nguồn và gọi POST /api/music/generate-from-source để bắt đầu cover.

Lưu ý: cover là endpoint đồng bộ — đơn chỉ được tiếp nhận khi phản hồi trả về, và theo đo đạc có thể chờ tới khoảng 230 giây. Hãy đặt timeout phía client từ 300 giây trở lên và đừng thử lại ngay sau khi timeout. Xem "Thời gian chờ và thiết lập timeout" trong Tổng quan API mới.

Trước tiên hãy hỏi GET /api/music/enhanced-upload/:id cho đến khi task.status là completed. Khi đó:

• task.song_id là ID bài hát thật và cũng là sourceClipId mà endpoint cover cần;
• nên truyền task.audio_url như sourceAudioUrl, để máy chủ xử lý được trường hợp clip nguồn và tài khoản thực thi khác nhau;
• task.task_id chỉ là ID tác vụ tải lên nâng cao, không dùng được làm sourceClipId;
• pending:enhanced-upload:* là ID giữ chỗ của giai đoạn xử lý, không dùng được cho cover.

Khi bắt đầu cover, dùng cùng API Key như khi tải lên nâng cao và ghép yêu cầu theo ánh xạ trường dưới đây.

Điền các tham số còn lại (lời, phong cách, tiêu đề, model) theo API cover từ clip nguồn. Khi endpoint cover trả về clips[].song_id mới, dùng POST /api/music/query để tra trạng thái tạo nhạc và âm thanh cuối cùng.