Tek adımda yükleme ve cover API'si

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

Uç nokta açıklaması

Tek adımda yükleme ve cover, bir ses dosyası veya ses URL'si gönderir ve o kaynak sesten yeni bir cover sürümü üretir.

Uç nokta: POST /api/music/upload-cover

Faturalama: Ücretli, şu anda varsayılan olarak çağrı başına 0,6 ¥. Bu uç nokta "yükle ve cover yap" içindir; görsel kapak yüklemekle ilgili değildir. Gerçekte tahsil edilen tutar güncel arka ofis fiyat yapılandırmasına göre belirlenir.

Max Mode / Variety: bu uç nokta isteğe bağlı max_mode ve variety (0-4) parametrelerini destekler. max_mode açıkken bu çağrı 2 kat fiyattan faturalanır (0,6 → 1,2 ¥ / çağrı); variety için ek ücret alınmaz. Anlamları ve nasıl gönderilecekleri Yeni API genel bakışı sayfasındaki "Gelişmiş parametreler" bölümündedir.

Bekleme süreleri ve zaman aşımları (önemli): bu uç nokta senkrondur — sipariş ancak yanıt geldiğinde kabul edilir ve üretime verilir. Ölçümlere göre isteklerin çoğu 1-3 saniyede yanıtlanır, yaklaşık %10'u 30 saniyeyi aşar ve en uzunu yaklaşık 230 saniyedir. İstemci zaman aşımını 300 saniye veya üzerine ayarlayın; yanıt gelmemesi hiçbir şey üretilmediği anlamına gelmez ve zaman aşımından hemen sonra yeniden denemeyin (siparişi çoğaltır ve tekrar ücret alır). Bağlantı koptuysa daha sonra GET /api/music/songs ile kontrol edin. Yeni API genel bakışı sayfasındaki "Bekleme süreleri ve zaman aşımı ayarları" bölümüne bakın.

Ses büyükse "yükleme" ve "cover" işlemlerini iki adıma ayırmanız önerilir

Bu uç nokta sesin tamamının istek gövdesine konmasını gerektirir: ses büyüdükçe gövde büyür ve tek bir ağ dalgalanması ya da zaman aşımı aktarımı yarıda keser, ardından sunucu unexpected end of JSON input döndürür (HTTP 400, ücret alınmaz).

Ses yaklaşık 8 MB'ı aşıyorsa, ağ kararsızsa veya aynı kaynak materyal tekrar kullanılacaksa iki adımlı biçime geçin:

1. POST /api/music/upload-source önce kaynak sesi yükler — ücretsiz, her zaman yeniden denenebilir — ve bir clip_id verir;
2. POST /api/music/generate-from-source bu clip_id ile cover'ı başlatır — ücret alınan adımın istek gövdesi yalnızca yaklaşık 250 bayttır.

Kaynak ses yükleme API'si, kaynak klipten cover API'si ve bu sayfanın sonundaki "Büyük dosyalar ve kesilen istekler" bölümüne bakın.

İstek parametreleri

Headers

Gövde parametreleri

cover_start_s ve cover_end_s saniye cinsindendir ve ondalık olabilir; başlangıç zamanı bitiş zamanından küçük olmalı ve kaynak sesin süresini aşmamalıdır. İki alan da atlanırsa sesin tamamı kullanılır. audio_weight, Suno'nun metadata.control_sliders.audio_weight alanına eşlenir ve sonucun referans sese ne kadar yaslandığını kontrol eder; 0.0-1.0 değerini alır ve yalnızca istekte geçerli bir file_url veya file_base64 referans sesi varsa gönderilebilir. 0 geçerli bir değerdir; alanı atlamak "belirtilmedi" anlamına gelir ve Suno'nun varsayılan davranışını korur. instrumental ve waitAudio JSON boolean olmalıdır, metin olmamalıdır.

Yükleme uç noktası varsayılan olarak asenkron döner. Yanıttaki clips[].status değeri pending iken audio_url alanının boş olması normaldir ve yüklemenin veya cover'ın başarısız olduğu anlamına gelmez; dönen gerçek song_id değerini kaydedin ve ses adresini okumadan önce şarkı sorgu uç noktasıyla tamamlanana kadar yoklayın.

İstek örneği

curl -X POST https://www.suno-api.io/api/music/upload-cover \
  -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",
    "prompt": "Yeni şarkı sözleri veya uyarlama yönü",
    "style": "Mandopop, acoustic guitar",
    "title": "Cover sürümü",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

Yanıt

{
  "code": 200,
  "message": "success",
  "data": {
    "upload": {
      "clip_id": "uploaded_clip_id",
      "status": "complete"
    },
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Cover sürümü",
        "status": "pending"
      }
    ]
  }
}

Büyük dosyalar ve kesilen istekler

Önerilen: yükleme ve cover'ı iki adıma ayırma

Tek seferlik uç nokta (bu) yükleme ile üretimi tek adımda birleştirir: büyük gövde o tek adımda bulunur, dolayısıyla kesildiğinde ne bir şeyin üretildiğini ne de ücret alındığını bilirsiniz.

Sonuç: ses yaklaşık 8 MB'ın üzerindeyse, ağ kararsızsa veya aynı materyal birkaç kez kullanılacaksa → iki adımlı biçim; ses çok küçük ve ağ kararlıysa → bu uç nokta daha zahmetsizdir.

400 unexpected end of JSON input ne demek

Anlamı, sunucunun aldığı JSON'un eksik olmasıdır (yanlış parametre değil, izin veya bakiye sorunu değil). Olasılık sırasına göre sık nedenler:

1. Büyük gövdenin aktarım ortasında kesilmesi: giriş katmanı hem "istemcinin kaç bayt göndereceğini bildirdiğini" hem de "gerçekte kaç baytın ulaştığını" kaydeder. Ölçülen örnek: istemci 14,17 MB bildirdi, gerçekte yalnızca 11,8–12,4 MB ulaştı ve üç isteğin tümü yaklaşık 1,6–1,7 sn civarında durdu; eksik bayt sayısı her seferinde farklıydı, bu da sabit bir sınıra değil aktarım kesintisine işaret eder (sunucu istek gövdesi boyutunu sınırlamaz).
2. Content-Length ile gerçekte gönderilen bayt sayısının uyuşmaması: Node.js'te bir metnin .length değerini (UTF-16 karakter sayısı) uzunluk olarak kullanmak, içerikte Çince veya çok baytlı metin varsa yanlış sonuç verir.
3. Gövdenin Buffer yerine metin olarak yazılması, böylece yazılan baytlar bildirilenle uyuşmaz.

Üç durum da ücretlendirmeden önce gerçekleşir, dolayısıyla masraf doğmaz.

İstemci tarafı öz denetim listesi

• Content-Length, Buffer.byteLength(json, 'utf8') (veya Buffer.from(json).length) ile elde edilir — json.length kullanılmaz;
• İstek gövdesi Buffer olarak yazılır, metin olarak yazılmaz;
• Soket / istek zaman aşımı ≥ 300 saniye;
• Ses yaklaşık 8 MB'ı aşıyorsa: file_url kullanın (gövde yalnızca birkaç yüz bayt) veya upload-source'un multipart yüklemesini kullanın ya da doğrudan iki adımlı biçime geçin;
• multipart isteklerde Content-Type elle ayarlanmaz (boundary'yi istemci ekler);
• "Gerçekte gönderilen bayt sayısı" yazdırılıp Content-Length ile karşılaştırılır;
• İki adımlı biçimde, 2. adımı göndermeden önce 1. adımın clip_id döndürdüğü ve status değerinin tamamlanmış olduğu doğrulanır.

Sık görülen hatalar

İlgili uç noktalar: Kaynak ses yükleme API'si (1. adım), kaynak klipten cover API'si (2. adım).