API muat naik diperkukuh

Dikemas kini 2026-09-18 · pasukan Suno-API

Penerangan endpoint

Muat naik diperkukuh menghantar fail audio tempatan; sistem melakukan pengukuhan di belakang tabir dan menghasilkan lagu lengkap yang boleh dimainkan. Panggilan hantar memulangkan maklumat tugasan dengan segera, dan klien menanyakan endpoint carian untuk kemajuan.

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

Carian satu tugasan: GET /api/music/enhanced-upload/:id

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

Carian senarai: GET /api/music/enhanced-upload

Pengebilan: 10 ¥ setiap panggilan, dibilkan di hadapan pada harga tetap suno-enhanced-upload. Jika tugasan gagal, atau dibatalkan pada peringkat yang dibenarkan, jumlah yang dibilkan di hadapan dipulangkan secara automatik. Jumlah yang benar-benar dicaj mengikut tetapan harga semasa dalam back-office.

Aliran panggilan

1. Panggil POST /api/music/enhanced-upload untuk memuat naik fail audio.
2. Simpan task_id yang dipulangkan.
3. Panggil GET /api/music/enhanced-upload/:id untuk menyemak kemajuan dan hasil.
4. Setelah Suno selesai menghasilkan render akhir, perkhidmatan menggunakan akaun Suno yang terikat pada tugasan itu untuk memanggil endpoint muat turun dibenarkan Studio dan menulis MP3 ke dalam perkhidmatan media CN2.
5. Tugasan hanya menjadi completed apabila aset CN2 sedia; ketika itu ambil alamat audio CDN daripada audio_url dalam respons.

/api/forbidden ialah alamat pemegang tempat yang mungkin muncul dalam metadata Suno Studio; ia bukan sumber yang boleh dimainkan atau dimuat turun. Ia tidak pernah dipulangkan kepada pelanggan dan tidak dijadikan asas penyempurnaan. Jika render sudah selesai tetapi CN2 masih menyediakan, endpoint akan terus memulangkan processing dan tidak memulangkan audio_url; klien perlu terus menanyakan dan tidak menganggap alamat kosong sebagai kegagalan.

Menghantar muat naik diperkukuh

Headers

Parameter borang

Contoh permintaan

Contoh di bawah menggunakan cara panggilan yang sama seperti semasa pengesahan produksi, tetapi API Key telah digantikan dengan pemegang tempat.

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

Mencari satu tugasan

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 semasa 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 apabila 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 tugasan

Pembatalan hanya mungkin selagi tugasan dan aliran backend masih pada peringkat queued. Setelah tugasan masuk leasing, running, processing atau sudah selesai, ia tidak boleh 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 tugasan sudah mula diproses, endpoint akan memulangkan:

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

Mencari senarai tugasan

Endpoint senarai hanya memulangkan tugasan muat naik diperkukuh milik pengguna bagi API Key semasa; tugasan penjanaan biasa, cover dan sambungan tidak bercampur.

Parameter pertanyaan

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 medan respons

Nota

• Buat masa ini endpoint hanya menyokong muat naik fail multipart; file_url dan file_base64 dalam JSON tidak disokong.
• Fail yang dimuat naik maksimum 80 MB.
• Endpoint hantar adalah tak segerak: respons queued bermakna tugasan sudah masuk baris gilir, bukan bermakna audio sudah siap.
• Pembatalan hanya terpakai pada tugasan yang belum mula diproses; setelah pemprosesan bermula, aliran akaun platform tidak dihentikan.
• Jangan dedahkan API Key sebenar dalam kod klien.

Memulakan cover selepas muat naik diperkukuh selesai

Setelah muat naik diperkukuh selesai, anda boleh menggunakan hasilnya sebagai klip sumber dan memanggil POST /api/music/generate-from-source untuk memulakan cover.

Perhatian: cover ialah endpoint segerak — pesanan hanya diterima apabila respons tiba, dan berdasarkan ukuran boleh menunggu sehingga kira-kira 230 saat. Tetapkan timeout klien kepada 300 saat atau lebih dan jangan cuba semula sejurus selepas timeout. Lihat "Masa menunggu dan tetapan timeout" dalam Gambaran keseluruhan API baharu.

Mula-mula pertanyakan GET /api/music/enhanced-upload/:id sehingga task.status menjadi completed. Ketika itu:

• task.song_id ialah ID lagu sebenar dan juga sourceClipId yang diperlukan endpoint cover;
• elok hantar task.audio_url sebagai sourceAudioUrl, supaya pelayan boleh mengendalikan kes klip sumber dan akaun pelaksana berbeza;
• task.task_id hanyalah ID tugasan muat naik diperkukuh dan tidak boleh digunakan sebagai sourceClipId;
• pending:enhanced-upload:* ialah ID pemegang tempat peringkat pemprosesan dan tidak boleh digunakan untuk cover.

Semasa memulakan cover, gunakan API Key yang sama seperti muat naik diperkukuh dan bina permintaan mengikut pemetaan medan di bawah.

Isi parameter lain (lirik, gaya, tajuk, model) mengikut API cover daripada klip sumber. Setelah endpoint cover memulangkan clips[].song_id baharu, gunakan POST /api/music/query untuk menyemak status penjanaan dan audio akhir.