Özel mod üretim API'si

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

Uç nokta açıklaması

Özel mod; sözler, stil ve başlık hazır olduğunda ve söyleyen sesi, stil etkisinin gücünü ve üretimin rastgelelik derecesini kontrol etmek istediğinizde uygundur.

Uç nokta: POST /api/music/create/custom

Faturalama: Ücretli, şu anda varsayılan olarak çağrı başına 0,6 ¥. Her çağrı genellikle 2 şarkı döndürür; 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.

İstek parametreleri

Headers

Gövde parametreleri

Gelişmiş parametre notları

Vokal cinsiyeti vocal_gender

• Erkek ses için m veya male, kadın ses için f veya female gönderin.
• Servis male ve female değerlerini sırasıyla m ve f olarak normalleştirir.
• instrumental=true iken üretim servisine vokal cinsiyeti parametresi gönderilmez.

Stil etkisi style_weight

Sonucun style_tags değerine ne kadar güçlü uyduğunu kontrol eder. Değer yükseldikçe sonuç, verdiğiniz stil etiketlerine daha çok uyar.

Rastgelelik weirdness_constraint

Sonucun ne kadar değiştiğini ve deneysel davrandığını kontrol eder. Yüksek değerler genelde daha fazla çeşitlilik; düşük değerler daha güvenli bir sonuç verir.

Her iki sayısal parametre de 0.0 ile 1.0 arasındadır ve 0 geçerli bir açık değerdir. Yalnızca alanı tamamen atlamak "belirtilmedi" anlamına gelir.

Doldururken bunların yüzde tamsayıları değil ondalık kesirler olduğunu unutmayın. Önerilen ölçek: 0.0–0.3 tutucu, 0.4–0.6 dengeli, 0.7–1.0 daha deneysel; belirgin bir tercihiniz yoksa 0.5 kullanın ya da alanları atlayın. Örnek: weirdness_constraint: 0.5, asla 50 veya 50%.

instrumental=true olduğunda sonuç enstrümantaldir, bu yüzden sözler ve vokal cinsiyeti sözlü bir şarkıdaki gibi işlemez; vokal gerekiyorsa false gönderin veya alanı atlayın. Mantıksal alanlar JSON true/false kullanmalıdır, metin değil.

Python istek örneği

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nGece denizin üzerine iniyor\nakşam rüzgârı pencereyi sıyırıp geçiyor',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Deniz kenarında akşam rüzgârı',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Kabul makbuzu modu (isteğe bağlı)

Bu uç nokta, basit mod üretim API'sindeki kabul makbuzu modunu da destekler: gövdeye "accept_mode": "async" (veya X-Accept-Mode: async başlığı) eklendiğinde uç nokta hemen 202 ve bir makbuz numarası döndürür, üretim arka planda sürer ve ilerlemeyi GET /api/music/requests/{request_id} ile izlersiniz.

Uzun bağlantı tutmaması gereken ya da zaman aşımının "hiç üretilmedi" diye okunmasını istemeyen istemciler için uygundur. Bu parametre olmadan davranış tam olarak eskisi gibidir.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Deniz kenarında akşam rüzgârı",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

Yanıt yapısı ve yoklama yöntemi, basit mod üretim API'sindeki "Kabul makbuzu modu" bölümündedir.

Parametre doğrulama

Bu durumlar HTTP 400 döndürür ve hatanın message alanı geçersiz alanı belirtir:

• style_weight veya weirdness_constraint bir sayı değil.
• Sayısal bir değer 0.0 altında veya 1.0 üzerinde.
• vocal_gender, m, f, male, female değerlerinden biri değil.

Metin alanı sınırları

Bu alanlar da aşıldığında HTTP 400 döndürür, üretime hiç girmez ve ön tahsilat yapılmaz. Sayım Unicode karakterle yapılır (bir Han karakteri 1 sayılır) ve baştaki/sondaki boşluklar da sayılır:

Hata mesajı style_tags must not exceed 1000 characters; received 2772 biçimindedir. İlk sözcük aşılan alanın adı, sonda ise ölçülen sayıdır, yani 400 aldığınızda alanları tek tek denemek yerine bu iki sayıya göre kısaltırsınız. Genel kurallar Yeni API genel bakışının "Metin alanı sınırları" bölümündedir.

Yanıt

Uç nokta genellikle 2 şarkı içeren bir dizi döndürür. Asenkron istek genelde pending durumuyla başlar; song_id değerini kaydedin ve nihai durumu ve ses adresini şarkı sorgulama API'sinden alın. Şarkı alanları basit mod üretim API'sindekiyle aynıdır.

Uyumlu alanlar

Yeni entegrasyonlar her yerde snake_case kullanmalıdır. Aynı istek hem snake_case hem camelCase taşıyorsa snake_case değeri geçerlidir.