Güçlendirilmiş yükleme API'si

2026-09-18 tarihinde güncellendi · Suno-API ekibi

Uç nokta açıklaması

Güçlendirilmiş yükleme yerel bir ses dosyası gönderir; sistem güçlendirmeyi arka planda yapar ve çalınabilir eksiksiz bir şarkı üretir. Gönderme çağrısı görev bilgisini hemen döndürür ve istemci ilerlemeyi sorgu uç noktasıyla yoklar.

Gönderme uç noktası: POST /api/music/enhanced-upload

Tek görev sorgusu: GET /api/music/enhanced-upload/:id

Görevi iptal etme: POST /api/music/enhanced-upload/:id/cancel

Liste sorgusu: GET /api/music/enhanced-upload

Faturalama: Çağrı başına 10 ¥; suno-enhanced-upload sabit fiyatıyla önceden tahsil edilir. Görev başarısız olursa ya da izin verilen aşamada iptal edilirse önceden alınan tutar otomatik iade edilir. Gerçekte tahsil edilen tutar güncel arka ofis fiyat yapılandırmasına göre belirlenir.

Çağrı akışı

1. Ses dosyasını yüklemek için POST /api/music/enhanced-upload çağırın.
2. Dönen task_id değerini saklayın.
3. İlerlemeyi ve sonucu görmek için GET /api/music/enhanced-upload/:id çağırın.
4. Suno nihai render'ı bitirdiğinde hizmet, o göreve bağlı Suno hesabıyla Studio'nun yetkili indirme uç noktasını çağırır ve MP3'ü CN2 medya hizmetine yazar.
5. Görev ancak CN2 varlığı hazır olduğunda completed olur; o anda yanıttaki audio_url üzerinden CDN ses adresi alınır.

/api/forbidden, Suno Studio üst verisinde görülebilen bir yer tutucu adrestir; çalınabilir veya indirilebilir bir kaynak değildir. Müşteriye hiçbir zaman döndürülmez ve tamamlanma kanıtı olarak kullanılmaz. Render bitmiş ama CN2 hâlâ hazırlanıyorsa uç nokta processing döndürmeye devam eder ve audio_url döndürmez; istemci yoklamayı sürdürmeli ve boş adresi başarısızlık saymamalıdır.

Güçlendirilmiş yükleme gönderme

Headers

Form parametreleri

İstek örneği

Aşağıdaki örnek, üretim doğrulamasındakiyle aynı çağrı biçimini kullanır; ancak API anahtarı bir yer tutucuyla değiştirilmiştir.

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"

Yanıt

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

Tek görev sorgulama

İstek örneği

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

İşleniyor yanıtı örneği

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

Tamamlandı yanıtı örneği

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

Görevi iptal etme

İptal, yalnızca görev ve arka uç iş akışı hâlâ queued aşamasındayken mümkündür. Görev leasing, running, processing aşamasına girdikten veya tamamlandıktan sonra iptal edilemez.

İstek örneği

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"

Yanıt

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

Görev işlenmeye başladıysa uç nokta şunu döndürür:

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

Görev listesini sorgulama

Liste uç noktası yalnızca mevcut API anahtarının ait olduğu kullanıcının güçlendirilmiş yükleme görevlerini döndürür; normal üretim, cover ve uzatma görevleri karışmaz.

Sorgu parametreleri

İstek örneği

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"

Yanıt

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

Yanıt alanları açıklaması

Notlar

• Bu uç nokta şu anda yalnızca multipart dosya yüklemeyi destekler; JSON file_url ve file_base64 desteklenmez.
• Yüklenen dosya en fazla 80 MB olabilir.
• Gönderme uç noktası asenkrondur: queued yanıtı görevin kuyruğa girdiği anlamına gelir, sesin bittiği anlamına gelmez.
• İptal yalnızca işlemeye başlamamış görevler için geçerlidir; işleme başladıktan sonra platform hesabının iş akışı kesilmez.
• İstemci kodunda gerçek API anahtarlarını açığa çıkarmayın.

Güçlendirilmiş yükleme bittikten sonra cover başlatma

Güçlendirilmiş yükleme tamamlandığında sonucu kaynak klip olarak kullanıp POST /api/music/generate-from-source çağırarak cover başlatabilirsiniz.

Dikkat: cover bir senkron uç noktadır — sipariş ancak yanıt geldiğinde kabul edilir ve ölçümlere göre bekleme yaklaşık 230 saniyeye kadar çıkabilir. İstemci zaman aşımını 300 saniye veya üzerine ayarlayın ve zaman aşımından hemen sonra yeniden denemeyin. Ayrıntılar için Yeni API genel bakışı sayfasındaki "Bekleme süreleri ve zaman aşımı ayarları" bölümüne bakın.

Önce GET /api/music/enhanced-upload/:id çağrısını task.status completed olana kadar yoklayın. O anda:

• task.song_id gerçek şarkı ID'sidir ve cover uç noktasının istediği sourceClipId de budur;
• task.audio_url değerini sourceAudioUrl olarak da göndermeniz önerilir; böylece sunucu kaynak klip ile çalıştıran hesabın farklı olduğu durumu ele alabilir;
• task.task_id yalnızca güçlendirilmiş yükleme görev ID'sidir ve sourceClipId olarak kullanılamaz;
• pending:enhanced-upload:* işleme aşamasının yer tutucu ID'sidir ve cover için kullanılamaz.

Cover'ı başlatırken güçlendirilmiş yüklemeyle aynı API anahtarını kullanın ve isteği aşağıdaki alan eşlemesine göre kurun.

Kalan söz, stil, başlık ve model parametrelerini kaynak klipten cover API'si sayfasına göre doldurun. Cover uç noktası yeni clips[].song_id döndürdüğünde, üretim durumunu ve nihai sesi görmek için POST /api/music/query çağırın.