Suno API belgelerine genel bakış

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

API anahtarı oluşturmak için e-posta ile kaydolmak yeterlidir. Bir üretim 0,6 ¥ tutarındadır ve 2 şarkı döndürür; MP3/WAV indirme, cover, Extend, stem ayrımı ve ses klonlama bunlara dahildir. Temel URL: https://www.suno-api.io.

Bu sayfada kullanılabilir modeller, tüm üretim ve düzenleme uç noktaları, faturalama ve önerilen okuma sırası anlatılır. İlk entegrasyonsa yukarıdan aşağıya okuyun; 401/403/429 için inceleme girişleri de burada.

Hızlı yanıtlar

API anahtarını nasıl alırım? E-posta ile kaydolun, konsolu açın, token yönetimine gidin ve bir token oluşturun. Telefon numarası ve kart gerekmez.

Bir çağrı ne kadar? Bir üretim 0,6 ¥ tutarındadır ve 2 şarkı döndürür. Durum sorguları, WAV, zaman damgalı sözler ve prompt önerileri ek ücret almaz.

Hangi modeller desteklenir? suno-v6 (varsayılan), suno-v6-wild ve suno-v6-mini. Standart üretim modelleri v5.5 ve öncesi kaldırıldı; mevcut çalışmalar etkilenmez.

Temel URL nedir? https://www.suno-api.io, Authorization: Bearer YOUR_API_KEY başlığıyla.

Şu anda kullanılabilir modeller

Normal şarkı üretiminde müşteri yalnızca suno-v6, suno-v6-wild ve suno-v6-mini belirtebilir. model gönderilmezse suno-v6 kullanılır.

suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 ve suno-v5-5 standart modelleri kaldırıldı. Geçmiş görevlerde bu adlar hâlâ görünebilir; bu yalnızca geçmiş veridir ve modelin yeni isteklerde kullanılabileceği anlamına gelmez. İstisna stem ayrımıdır — bkz. Stem API'si (vokal/altyapı ayrımı).

Kimlik doğrulama

Tüm genel API anahtarı uç noktaları aynı başlıkları kullanır:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Temel URL:

https://www.suno-api.io

Genel parametre kuralları

• İstek gövdesindeki number JSON sayısı olmalıdır, yüzde metni olamaz. %50 yoğunluk 0.5 olarak yazılır; 50 veya 50% yazılmaz.
• boolean true veya false olmalıdır. true, false, 0, 1 gibi alternatifler göndermeyin.
• "Hayır" olarak işaretlenen alanlar tamamen gönderilmeyebilir. Bir parametreden emin değilseniz alanı atlayın ve hizmetin varsayılan davranışını kullanmasına izin verin; "gönderilmedi" yerine boş metin, null veya 0 göndermeyin, çünkü bazı sayısal alanlarda 0 geçerli bir değerdir.
• Alan adları yazıma duyarlıdır. Her uç nokta sayfası önerilen alanı ve uyumlu diğer adları listeler; tablodaki gibi gönderin. snake_case ve camelCase'in ikisinin de kabul edildiği yerlerde ikisini birlikte göndermeyin.
• _s veya Seconds ile biten tüm süre alanları saniye cinsindendir ve ondalık kabul eder. Unix zaman damgaları için saniye mi milisaniye mi olduğu ayrıca belirtilir.
• pending: ile başlayan bir kimlik platformun yer tutucusudur, gerçek şarkı kimliği değildir. Yalnızca uç noktanın açıkça belgelediği yerlerde kullanın; aksi halde gerçek song_id gelene kadar bekleyin.

Metin alanı sınırları

Sınır aşılırsa doğrudan HTTP 400 döner: üretim başlamaz, ön ödeme alınmaz ve görev kaydı oluşmaz. Sayım Unicode karakterle yapılır (bir ideogram 1 sayılır) ve baştaki/sondaki boşluklar da sayılır.

Hata message alanı ilgili alanı ve ölçülen uzunluğu verir; metni kısaltmak için bu iki sayı yeterlidir:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Şunlar için geçerlidir: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

Bir istisna: POST /api/music/sounds için description alanı 100 karakterle sınırlıdır, çünkü ses efekti yolu platformun daha kısa sınırını kullanır.

Asenkron üretim ve ses adresleri

Müzik üretim uç noktaları varsayılan olarak asenkron çalışır. İlk yanıttaki status pending, submitted veya processing ise audio_url, video_url ve cover_url alanlarının boş olması normaldir ve görevin başarısız olduğu anlamına gelmez. Gerçek song_id (veya dönen client_request_id) değerini kaydedin ve ilgili sorgu uç noktasını yoklayın; ses adresini yalnızca durum tamamlandıktan sonra okuyup indirin.

⚠️ Ses adresleri 7 gün sonra geçersiz olur — dosyaları zamanında taşıyın

audio_url, wav_url, video_url ve indirme uç noktalarının döndürdüğü adresler platformun nesne depolamasından sunulur ve varsayılan olarak 7 gün sonra geçersiz olur (dosyalar geri dönüştürülür; eski adres 404 verir / indirilemez).

• Bu 7 gün içinde dosyaları kendi depolamanıza taşıyın (kendi nesne depolamanız, bir CDN veya sunucu diski). Adreslerimizi uzun ömürlü bağlantı olarak kullanmayın.
• Geçersiz olan adres şarkıyı yeniden üretmeyi gerektirmez ve ek ücret doğurmaz: şarkı sorgu API'sini (veya medya indirme API'sini) yeniden çağırın ve o şarkı için yeni geçerli adres alın.

Bekleme süreleri ve zaman aşımı ayarları

Üretim uç noktaları senkron çalışır: sipariş ancak yanıt geldiğinde kabul edilip platforma iletilir. Ondan önce hizmet bir hesap ayarlamalı ve gerekli güvenlik kontrolünü geçmelidir; ara yanıt yoktur ve başka hiçbir uç nokta bu siparişi göremez. Dolayısıyla "bir şey üretildi mi" sorusunun tek güvenilir kanıtı yanıtın kendisidir, beklerken gözlemlenenler değil.

Ölçülen bekleme süreleri (üretim, /api/music/create ailesi, 18–20 Eylül 2026)

• İsteklerin yaklaşık %10'u 30 saniyeden uzun, %1'i 1–2 dakika sürer. Yavaş bir istek genellikle bu kez önce bir güvenlik kontrolü gerektiği anlamına gelir.
• İstek alanları, yanıt şekli, hata kodları ve faturalama değişmedi; mevcut entegrasyonların yalnızca istemci zaman aşımını yükseltmesi yeterli, başka kod değişikliği gerekmez.

Entegrasyon gereksinimleri

1. İstemci zaman aşımını 300 saniye veya daha fazla yapın. Varsayılanı 30, 60 veya 120 saniye olan istemciler beklerken bağlantıyı koparır.
2. Yanıt gelmemesi, üretim olmadığı anlamına gelmez. Zaman aşımı veya kopan bağlantıda sipariş kabul edilmiş ve üretiliyor olabilir.
3. Zaman aşımından sonra hemen yeniden denemeyin: aynı isteği tekrar göndermek yeni bir sipariş yaratır ve yeniden ücret alır.
4. Bağlantı koptuysa bir süre sonra GET /api/music/songs ile şarkılarınızı en yeniden eskiye listeleyin; kabul edilen siparişler normal şekilde görünür. Siparişin gerçekten olmadığını doğruladıktan sonra yeniden gönderin.
5. Sorun bildirirken X-Oneapi-Request-Id yanıt başlığını ekleyin; böylece o çağrı doğrudan bulunabilir.

Uzun bağlantı tutmak istemiyor musunuz? Kabul makbuzu modunu kullanın. POST /api/music/create ve POST /api/music/create/custom isteğe bağlı bir kabul makbuzu destekler: gövdeye "accept_mode": "async" (veya X-Accept-Mode: async başlığını) ekleyin; uç nokta hemen 202 ve makbuz numarası döndürür, üretim arka planda sürer ve ilerlemeyi GET /api/music/requests/{request_id} ile izlersiniz. Zaman aşımı birkaç on saniye olan bir istemci artık "yanıt yok"u "üretim yok" sanmaz ve tekrarlarla iki kez ücret ödemez. Ayrıntı için Basit mod üretim API'si içindeki "Kabul makbuzu modu" bölümüne bakın.

Referans: python requests için timeout=300, urllib için urlopen(..., timeout=300), Node için req.setTimeout(300000), curl için --max-time 300.

Önerilen uç nokta listesi

Yukarıdaki /api/voice/clone/* ve /api/music/generate-with-voice, erken ses klonlama zincirine aittir ve yeni entegrasyonlar için önerilmez; bunun yerine 【Önerilir】 Ses profili API'sini kullanın.

Gelişmiş parametreler: Max Mode ve Variety

Üretim uç noktaları bu iki isteğe bağlı parametreyi destekler (gönderilmezse davranış ve fiyat aynı kalır):

Destekleyen uç noktalar: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• İki kat fiyatın pratikteki hâli: çağrı başına 0,6 ¥ olan bir uç nokta max_mode ile 1,2 ¥ olur; seçilen sesle üretim çağrı başına 1,2 ¥, Max Mode ile 2,4 ¥ olur; 【Önerilir】 Ses profili API'sinin ses cover'ı da çağrı başına 1,2 ¥ ( max_mode ile 2,4 ¥).
• variety yalnızca suno-v6 ailesinde (suno-v6, suno-v6-wild, suno-v6-mini) geçerlidir; diğer modellerde gönderilirse 400 döner.
• Ses efektleri, stem ayrımı, concat, WAV ve Studio düzenleme işlemleri (kırpma, bölüm silme, fade, tersten çalma, hız vb.) bu parametreleri bilmez — açıkça gönderilirse 400 döner, böylece bir parametre sessizce yok sayılmaz.
• variety 0-4 tam sayıdır; style_weight ve weirdness_constraint 0-1 arası ondalıktır, yani ölçekler farklıdır.

Şarkıların ortak yanıt alanları

Üretim, cover, extend, ayrım ve sorgu uç noktaları genellikle şu alanlara sahip bir şarkı dizisi döndürür:

Entegrasyonun dört adımı (asgari örnek)

Bu dört adımla ilk şarkınızı alırsınız; her adımın tam alan listesi, önerilen uç nokta listesindeki ilgili sayfada.

# 1) Üretim gönder: 0,6 ¥, 2 şarkı döndürür
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Turkish pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) status completed olana kadar yokla (3-5 saniye iyi bir aralık)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "1. adımda dönen song_id"}'

# 3) Medya adresi al: okuma uç noktaları ücretsizdir; song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "aynı song_id", "kind": "song"}'

Bir şey ters giderse: 401 / 402 / 403 / 429 için hata listesi; zaman aşımı ve çift ücret için yukarıdaki "Bekleme süreleri ve zaman aşımı ayarları"; her uç noktanın açıklaması için aşağıdaki liste.

Öneriler

• Yeni entegrasyonlar her yerde suno-v6 kullanmalı.
• Varsayılan fiyat belirtilen uç noktalarda gerçek tutar, güncel arka uç fiyat yapılandırmasına ve istenen modele göre belirlenir.
• Üretim uç noktaları önce görev döndürür; nihai sesi /api/music/query ile alın.
• wait_completion=true bitene kadar bloklar ve düşük hacimli testler için uygundur; üretimde asenkron yoklama daha iyidir.
• Üretim uç noktaları uzun sürebilir — istemci zaman aşımını 300 saniye veya üzerine ayarlayın ve "yanıt yok"un "üretim yok" demek olmadığını unutmayın.
• Yükleme, cover, değiştirme ve WAV platform hesaplarına ve kaynak klip izinlerine bağlıdır; hata durumunda önce message veya error_message alanını okuyun.

Bu belge hakkında

Bu sayfa, Create UI'nin gerçekte sunduğu yeteneklere göre yeniden düzenlendi; yeni entegrasyonlar önce burayı okumalı. Eski API belgeleri, önceki yöntemi sürdürmek isteyenler için "Eski API belgeleri (uyumlu)" bölümünde duruyor.