API unggahan yang disempurnakan

Diperbarui 2026-09-18 · tim Suno-API

Deskripsi endpoint

Unggahan yang disempurnakan mengirim berkas audio lokal; sistem melakukan penyempurnaan di latar belakang dan menghasilkan lagu lengkap yang bisa diputar. Panggilan kirim langsung mengembalikan informasi tugas, dan klien melakukan polling ke endpoint kueri untuk memantau kemajuan.

Endpoint kirim: POST /api/music/enhanced-upload

Kueri satu tugas: GET /api/music/enhanced-upload/:id

Batalkan tugas: POST /api/music/enhanced-upload/:id/cancel

Kueri daftar: GET /api/music/enhanced-upload

Biaya: 10 ¥ per panggilan, ditagih di muka dengan harga tetap suno-enhanced-upload. Bila tugas gagal, atau dibatalkan pada tahap yang diizinkan, jumlah yang ditagih di muka dikembalikan otomatis. Jumlah yang benar-benar ditagih mengikuti konfigurasi harga di back-office saat ini.

Alur pemanggilan

1. Panggil POST /api/music/enhanced-upload untuk mengunggah berkas audio.
2. Simpan task_id yang dikembalikan.
3. Panggil GET /api/music/enhanced-upload/:id untuk memeriksa kemajuan dan hasil.
4. Setelah Suno menyelesaikan rendering akhir, layanan memakai akun Suno yang terikat pada tugas itu untuk memanggil endpoint unduhan terotorisasi Studio dan menulis MP3 ke layanan media CN2.
5. Tugas baru menjadi completed setelah aset CN2 siap; saat itulah alamat audio CDN diambil dari audio_url pada respons.

/api/forbidden adalah alamat pengganti yang bisa muncul di metadata Suno Studio; itu bukan sumber daya yang bisa diputar atau diunduh. Alamat ini tidak pernah dikembalikan ke pelanggan dan tidak dipakai sebagai dasar penyelesaian. Bila rendering sudah selesai tetapi CN2 masih menyiapkan, endpoint tetap mengembalikan processing dan tidak mengembalikan audio_url; klien sebaiknya terus melakukan polling dan tidak menganggap alamat kosong sebagai kegagalan.

Mengirim unggahan yang disempurnakan

Headers

Parameter form

Contoh permintaan

Contoh di bawah memakai cara pemanggilan yang sama seperti saat validasi produksi, tetapi API Key sudah diganti dengan pengganti.

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"

Respons

{
  "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"
  }
}

Mengueri satu tugas

Contoh permintaan

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

Contoh respons saat diproses

{
  "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
    }
  }
}

Contoh respons saat selesai

{
  "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
    }
  }
}

Membatalkan tugas

Pembatalan hanya mungkin selama tugas dan alur backend masih berada di tahap queued. Setelah tugas masuk leasing, running, processing, atau sudah selesai, tugas tidak bisa dibatalkan.

Contoh permintaan

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"

Respons

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

Jika tugas sudah mulai diproses, endpoint mengembalikan:

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

Mengueri daftar tugas

Endpoint daftar hanya mengembalikan tugas unggahan yang disempurnakan milik pengguna pemegang API Key saat ini; tugas pembuatan biasa, cover, dan extend tidak tercampur.

Parameter kueri

Contoh permintaan

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"

Respons

{
  "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
      }
    ]
  }
}

Penjelasan kolom respons

Catatan

• Saat ini endpoint hanya mendukung unggahan berkas multipart; file_url dan file_base64 dalam JSON tidak didukung.
• Berkas yang diunggah maksimal 80 MB.
• Endpoint kirim bersifat asinkron: respons queued berarti tugas sudah masuk antrean, bukan berarti audionya sudah selesai.
• Pembatalan hanya berlaku untuk tugas yang belum mulai diproses; setelah pemrosesan dimulai, alur akun platform tidak dihentikan.
• Jangan mengekspos API Key asli di kode klien.

Memulai cover setelah unggahan yang disempurnakan selesai

Setelah unggahan yang disempurnakan selesai, Anda bisa memakai hasilnya sebagai clip sumber dan memanggil POST /api/music/generate-from-source untuk memulai cover.

Perhatian: cover adalah endpoint sinkron — pesanan baru diterima saat respons tiba, dan menurut pengukuran bisa menunggu hingga sekitar 230 detik. Setel timeout klien 300 detik atau lebih dan jangan mencoba ulang langsung setelah timeout. Lihat "Waktu tunggu dan pengaturan timeout" di Ringkasan API baru.

Pertama, polling GET /api/music/enhanced-upload/:id sampai task.status bernilai completed. Saat itu:

• task.song_id adalah ID lagu asli dan sekaligus sourceClipId yang dibutuhkan endpoint cover;
• sebaiknya kirim task.audio_url sebagai sourceAudioUrl, agar server bisa menangani kasus clip sumber dan akun pelaksana berbeda;
• task.task_id hanya ID tugas unggahan yang disempurnakan dan tidak bisa dipakai sebagai sourceClipId;
• pending:enhanced-upload:* adalah ID pengganti tahap pemrosesan dan tidak bisa dipakai untuk cover.

Saat memulai cover, gunakan API Key yang sama seperti unggahan yang disempurnakan dan susun permintaan sesuai pemetaan kolom berikut.

Isi parameter lainnya (lirik, gaya, judul, model) sesuai API cover dari clip sumber. Setelah endpoint cover mengembalikan clips[].song_id baru, gunakan POST /api/music/query untuk memeriksa status pembuatan dan audio akhirnya.