【Önerilir】 Ses profili API'si

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

✅ Yeni entegrasyonlar için bu yolu öneriyoruz. Çok sayıda kullanıcının gerçek değerlendirmelerine göre bu yolla üretilen şarkılar orijinal sesi iyi korur: bitmiş kayıttaki vokal, yüklediğiniz örnekteki kişiye daha yakın çıkar. Bu nedenle şu anda müşterilere önerdiğimiz yol budur.

Karşılaştırma: önceki ses klonlama ve belirtilen sesle üretim API'si hâlâ çalışır, ancak menüde "önerilmez" olarak işaretlidir ve yeni entegrasyonlar için önerilmez.

• Belge tarihi: 2026-09-26
• Kapsam: kendi sesinizi oluşturma → seçtiğiniz şarkıyı bu sesle cover'lama / yeni bir şarkı söyleme → ilerlemeyi izleme → çıktıyı indirme
• Tüm uç noktalar, alanlar ve yanıtlar gerçek çağrılarla doğrulandı ("ölçüldü" diye işaretlenenler ayrıntılı doğrulandı)

Not: bu belge yalnızca çağırmanız gereken uç noktaları anlatır. Malzeme işleme, görev planlama ve içerik denetimi sunucu tarafında otomatik yapılır; istemci bunları uygulamaz.

0. Beş dakikada başlangıç

Dört adım, tek bir vokal örneğinden iki bitmiş şarkı çıkarmaya yeter.

① Ses oluştur    POST /api/music/voice-profile/create      → voice_id al (status=ready)
② Cover'la       POST /api/music/voice-profile/cover       → hemen 2 song_id al
③ İzle           POST /api/music/query                     → status=completed olana kadar yokla
④ İndir          GET  /api/music/download?song_id=…&kind=mp3

En küçük çalışan örnek (curl):

API_KEY="sk-anahtariniz"
BASE="https://www.suno-api.io"

# ① Sesi oluştur (bir vokal örneği yükleyin; 10 sn ve üzeri, 10 MB altı önerilir)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=Sesim" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② Bu sesle bir şarkıyı cover'la (song_clip_id = cover'lanacak şarkının clip id'si)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\nsarki sozu…",
        "style_requirements": "yavaş folk, akustik gitar",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ Yokla (birden çok id'yi virgülle ayırarak tek seferde gönderin)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ Bitince mp3'ü indirin (dosya yalnızca status=completed iken gelir)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. Ortak kurallar

1.1 Alan adı ve ortam

Aşağıdaki tüm yollar Base URL'ye göre görelidir; örneğin POST /api/music/voice-profile/create için tam adres https://www.suno-api.io/api/music/voice-profile/create olur.

1.2 Kimlik doğrulama

Tüm uç noktalar aynı istek başlığını kullanır; değeri konsolda oluşturduğunuz API anahtarıdır:

Authorization: Bearer sk-xxxxxxxx

• Bearer öneki isteğe bağlıdır; sk- öneki de (Authorization: sk-xxx de aynı şekilde çalışır).
• Anahtar yok veya geçersiz → HTTP 401, gövde {"success":false,"message":"…"} biçimindedir (metin isteğin diline göre değişir).
• Her anahtar yalnızca kendi hesabının şarkılarını ve seslerini görebilir ve işleyebilir.

1.3 İstek gövdesi biçimleri

• Ses oluşturma: multipart/form-data (dosya yükleme) önerilir; application/json (URL veya base64) da desteklenir.
• Diğer uç noktalar: application/json.

1.4 İki yanıt kabuğu (müşterinin bilmesi gereken yalnızca bu ikisi)

"Ses yönetimi" uç noktaları (create / create-from-clip / list / detail / delete) iş kabuğunu kullanır:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

"Sesle cover" üretim kanalından geçer ve üretim kabuğunu kullanır: başarı code/message/data, hata ise error nesnesidir:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

Nasıl karar verilir: önce HTTP durum koduna, sonra success === false değerine, en son code !== 200 veya error varlığına bakın. İş hatası HTTP'nin 200 dışında olmasını garanti etmez (ses yönetimi uç noktaları hata durumunda da HTTP 200 döner), bu yüzden yalnızca durum koduna bakamazsınız.

1.5 Tekrarsızlık (idempotency)

Ses oluşturma ("mevcut sesten oluşturma" dâhil) gerçekten idempotenttir: aynı anahtar altında aynı client_request_id yeniden gönderildiğinde yalnızca bir ses oluşturulur ve ikinci deneme doğrudan ilk sonucu döndürür (success=true, aynı voice_id). Amaç, istemcinin kendi id'sini (örneğin bir UUID) üretip zaman aşımından sonra yeniden denerken aynı değeri kullanmasıdır.

Cover gönderimi istek düzeyinde tekilleştirme yapmaz (ücretli bir üretimdir), iki noktaya dikkat edin:

1. Gönderim kimliği X-Create-Ui-Client-Request-Id: <gönderim id'niz> başlığına konur. Sunucu tarafındaki görev kaydına yazılır ve sonraki incelemeyi kolaylaştırır; ancak çift ücretlendirmeyi engellemez.
2. Zaman aşımı ≠ başarısızlık: istek kabul edilmiş ve üretimde olabilir. Yeniden denemeden önce GET /api/music/songs?p=1&page_size=20 ile (sayfalama parametreleri p / page_size; uyumlu yazım ps de olur) generation_type=voice_profile_cover olan yeni bir şarkının çıkıp çıkmadığını kontrol edin ve yalnızca yoksa aynı isteği yeniden gönderin.

create ve create-from-clip gövdeleri de client_request_id alanını kabul eder (§3 ve §4).

1.6 Ücretlendirme özeti

Fiyatlar her an herkese açık bir uç noktadan okunabilir, bu yüzden sabit değer yazmayın (§9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← sesle cover'ın temel fiyatı
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← güçlendirilmiş klon fiyatı
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

Cover peşin ücret + hata durumunda iade ile çalışır:

• Reddedilen istek (hatalı parametre, platformun 4xx/5xx'i, bakiyenin kendisinin yetersiz olması) ücretlendirilmez — var olmayan bir sesle gönderimde ölçümlerimizde bakiye hiç değişmedi (delta = 0);
• Kabul edilip sonunda başarısız olan görev (platform servis hatası dâhil) sunucu tarafındaki iade yolundan geçer ve peşin alınan tutarı geri verir.

1.7 Durum sözlüğü

Sesin status değeri:

Şarkının status değeri (sorgu uç noktalarının döndürdüğü değer):

2. Uç noktalara genel bakış

3. Ses oluşturma

POST /api/music/voice-profile/create

Bir vokal ses parçasını "ses" olarak kaydedin ve voice_id alın. Platform için ses, "bir ses dosyası + katalogdaki clip'i" demektir; bu yüzden oluşturma başarılı olduğunda o kaynak ses kalıcı olarak saklanır (sonraki cover'lar için).

3.1 Üç giriş biçimi (birini seçin)

Biçim A: multipart dosya yükleme (önerilir)

Content-Type: multipart/form-data

file=<ses ikili verisi>      # zorunlu
title=<ses adı>              # isteğe bağlı; boşsa uzantısız dosya adı
file_name=<özgün dosya adı>
source_file_name=<özgün dosya adı>
source_kind=upload|record    # isteğe bağlı, kaynak işareti (yükleme / kayıt); varsayılan upload
enhanced=false|true          # isteğe bağlı, true = güçlendirilmiş klon (§3.5'e bakın)
client_request_id=<idempotency anahtarı>   # isteğe bağlı
voice_id=<kendi ID'niz>      # isteğe bağlı, genelde kullanılmaz

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=Sesim" \
  -F "source_kind=upload"

Biçim B: JSON + herkese açık ses URL'si

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "Sesim"
      }'

• URL, herkese açık erişilebilen bir HTTPS doğrudan bağlantısı olmalıdır; sunucu bir kez indirip nesne depolamamıza aktarır.
• Adresi audio_url alanına da koyabilirsiniz, etki aynıdır (ikisi de gönderilirse file_url kazanır).
• Adres zaten bu platformun nesne deposundaysa (*.myqcloud.com/create-ui/voice-source/...) yeniden indirilmez: doğrudan kaydedilir.

Biçim C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "Sesim"
}

• Hem data:audio/xxx;base64, öneki hem de saf base64 kabul edilir.
• Boyut sınırlıdır (base64 1,33× şişirir), büyük dosyalar için A biçimini kullanın.

3.2 Ses gereksinimleri

3.3 Yanıt

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "Sesim",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

Alan açıklaması (create / list / detail aynı alan kümesini paylaşır):

created_at / updated_at saniye düzeyinde zaman damgalarıdır (10 hane), milisaniye değildir.

3.4 Sık görülen hatalar

3.5 Güçlendirilmiş klon (enhanced=true)

"Ses örneğinin kendisi telifli şarkı sözü taşıyor / güçlendirilmiş yükleme gerekiyor" durumları için. Fiyat güçlendirilmiş yükleme fiyatıdır (varsayılan çağrı başına 10 ¥, hata olursa otomatik iade):

• Yanıt hemen status=processing + task_id olur (bu aşamada clip_id yok) ve eşzamansız çalışır;
• İşlem sürerken ilerlemeyi GET /api/music/voice-profile/{voice_id} ile sorgulayın; progress_percent / progress_stage / progress_message döner;
• Bitince status ready olur ve clip_id, audio_url, image_url tamamlanır;
• Başarısız olursa status=failed olur ve error_message yaklaşık "güçlendirilmiş yükleme başarısız oldu; ücret otomatik iade edildi, sonra yeniden deneyin" der;
• Güçlendirilmiş klon normal oluşturmadan belirgin biçimde uzun sürer (dakikalar), bu yüzden eşzamanlı zaman aşımı mantığıyla beklemeyin.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=Sesim" -F "enhanced=true"

4. Mevcut sesten ses oluşturma

Yeniden yüklemek istemiyorsanız: zaten yüklediğiniz veya ürettiğiniz bir sesi doğrudan sese kopyalayın. Ücretsiz ve idempotent.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: hesabınızdaki tamamlanmış bir sesin clip id'si (şarkının song_id'siyle aynı).
• Aynı clip yeniden gönderilirse yeni kayıt açılmaz; mevcut ses doğrudan reused: true ile döner (ölçüldü).

Yanıt, §3.3'teki tüm alanlar artı iki salt okunur alandır:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

Hatalar (message döndüğü gibi; doğrudan göstermeniz veya yerelleştirmeniz önerilir):

5. Ses listesi / ayrıntı / silme

5.1 Liste

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "Sesim", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

Alanlar tam olarak §3.3'teki gibidir. Silinmiş sesler varsayılan olarak dönmez.

5.2 Ayrıntı

GET /api/music/voice-profile/{voice_id}

Tek bir ses nesnesi döner (data nesnenin kendisidir, dizi değil). Güçlendirilmiş klon sürerken ek olarak:

5.3 Silme

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• Silme sonrası ses listeden kaybolur ve yeni cover'larda kullanılamaz: bu voice_id ile gönderim 400 döner (§6.4'e bakın).
• Onunla üretilmiş şarkılar hiç etkilenmez; çalma, indirme, devam ettirme, değiştirme ve ayırma eskisi gibi çalışır.
• Var olmayan veya bu hesaba ait olmayan bir sesi silmek {"success":false,"message":"voice not found"} döner.

6. Sesle cover (çekirdek uç nokta)

POST /api/music/voice-profile/cover
Content-Type: application/json

Bir gönderim 2 şarkı üretir (normal üretimdeki gibi).

6.1 İki senaryo

Yanıttaki resolved_scene cover veya sing döner, böylece hangi yoldan gidildiğini görebilirsiniz.

6.2 İstek alanları

Ayrıca X-Create-Ui-Client-Request-Id: <aynı gönderim id'si> başlığını da göndermenizi öneririz: yalnızca bu, sunucu tarafındaki görev kaydına yazılır ve sonraki inceleme için ana anahtar olur (§1.5'e bakın).

Birim uyarısı: audio_weight / style_weight / weirdness_constraint 0–1 arası ondalık, variety 0–4 arası tam sayı, duration ise saniyedir. Karıştırmak reddedilmeye veya tuhaf sonuca yol açar.

Senaryo B'de şarkı sözü isteğe bağlıdır (model kendi halleder), ancak belirli bir içeriğin söylenmesi gerekiyorsa lyrics mutlaka gönderin.

6.3 Yanıt

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[Görev] Bu bir cover'dır. … (sunucunun sabit yapı bölümü + sizin girdiğiniz cover / stil gereksinimleri)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

Önemli noktalar:

1. Bitmiş kayıtları clips[].song_id ile tanımlayın (bu uç nokta id alanı döndürmez).
2. Hemen 2 song_id alırsınız, ancak status hâlâ processing (yalnızca kabul edildiği anlamına gelir) ve audio_url boştur; indirmeden önce completed olana kadar yoklamalısınız. play_url platformun ön dinleme akışıdır, gönderim aşamasında bile görünebilir ve süresi dolar.
3. description, sunucunun sonunda gönderdiği prompt'tur (sabit yapı bölümü + girdiğiniz cover_requirements / style_requirements); sonucu incelerken çok işe yarar.
4. source_updates sunucunun malzeme işleme sonucudur, istemci yok sayabilir.
5. Gönderdiğiniz title sunucu görev kaydına yazılır ve sonraki sorgularda song_title olarak görünür; gönderim yanıtındaki clips[].song_title genelde boştur ve bu normaldir.

6.4 Hatalar

{ "error": { "message": "bu ses yok veya silinmiş (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

Yetersiz bakiye gönderim aşamasında doğrudan ücretlendirme hatası verir ve yarım kalmış görev bırakmaz.

6.5 Kullanılabilir modeller (müşteriye dönük adlar)

Müşteriye dönük model adlarını (yukarıdakileri) kullanın. chirp-* platformun iç adlarıdır, doğrudan kullanılmamalıdır.

7. İlerlemeyi izleme

7.1 Toplu sorgu (önerilir)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids virgülle ayrılmış bir dizedir (dizi değil).
• Yanıt çıplak bir dizidir (doğrudan [...], success / data kabuğu yok):

[
  {
    "song_id": "0f2a…",
    "song_title": "İki Kaplan",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[Görev] Bu bir cover'dır. … (sunucunun son prompt'u)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

Yoklama tavsiyesi: 5–10 saniyede bir, toplam 10–15 dakika zaman aşımı (en yavaş ölçülen soğuk hesap yaklaşık 4,5 dakika sürdü; çok azı daha uzun). Bittiğini audio_url boş mu diye değil, status ile değerlendirin.

Uyumluluk notu: bu uç nokta şarkıları song_id ile tanımlar; erken bazı yanıtlarda id alanı göründü, bu yüzden row.song_id || row.id güvenli okuma yoludur.

7.2 Tek şarkı ayrıntısı

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "İki Kaplan",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "İki Kaplan",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• Burada created_at / completed_at Unix saniyesidir (toplu sorgunun ISO dizelerinden farklı, istemciler ayırmalı).
• wav_url / video_url bu platformun indirme girişleridir (geçerli alan adına göre) ve GET dosyayı verir; platform o çıktıyı üretmediyse boş dizedir.
• parameter_retention, o şarkının hangi gönderim parametrelerine kadar izlenebileceğini söyler: core_parameters_available=true çekirdek parametrelerin (şarkı sözü / stil / kaynak) sorgulanabilir olduğunu, extended_parameters_available=false ise yukarıda listelenen genişletilmiş parametrelerin saklanmadığını gösterir (sesle cover'lar şu anda bu kategoride).

7.3 Eserlerim

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=anahtar kelime

Sayfalama parametreleri: p (sayfa numarası, 1'den başlar) / page_size (sayfa başına kayıt; uyumlu yazım ps). İsteğe bağlı status ve q (başlıkta anahtar kelime). Varsayılan olarak oluşturma zamanına göre azalan sıralama.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "İki Kaplan",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

generation_type=voice_profile_cover ile "sesle cover'dan çıkan şarkılar"ı diğer üretim sonuçlarından ayırabilirsiniz.

8. Bitmiş şarkıları indirme

8.1 mp3'ü doğrudan almak (önerilir, ücretsiz)

Üçü de olur; birini seçin:

1. Sorgu sonucundaki audio_url'yi kullanmak (nesne deposuna doğrudan bağlantı, en kolayı).
2. GET /api/music/download?song_id=<id>&kind=mp3 → doğrudan ses bayt akışını döndürür (dosya adı Content-Disposition içinde gelir).
3. POST /api/music/download-url (imzalı geçici adres almak için).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

kind değerleri: mp3 (song ile aynı) / playback (akış oynatma) / wav / video / lyrics / timestamped_lyrics. timestamped_lyrics (.lrc) şu anda yalnızca bazı şarkılarda var; başarısız olursa dosyayı zaman damgalı şarkı sözü API'si ile kendiniz üretin. Yanıt doğrudan dosya bayt akışıdır, Content-Type ve Content-Disposition (dosya adı) hazırdır; GET /api/music/songs/{song_id} çıktısındaki wav_url / video_url aynı girişin kind=wav|video hâlidir.

8.2 wav'a çevirme / şarkı sözü / üst veri (ücretli)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files şunları kabul eder: mp3 / wav / lyrics / metadata, tek seferde en fazla 10 şarkı.
• Başarılı şarkı sayısına göre ücretlendirilir (şarkı başına 0,2 ¥); tümüyle başarısız olan şarkı ücretlendirilmez ve başarısız bir biçim yalnızca songs[].errors içinde görünür.
• Daha önce aldığınız dosyaları yeniden almak için önce ücretsiz POST /api/music/free2/cached (aynı song_ids + files) ile arşivlenmiş adresleri alın; yanıtındaki songs[].missing_files önbellekte olmayan ve yeniden hazırlanması gereken biçimleri listeler.

9. Fiyat sorgulama

GET /api/pricing/catalog

Kimlik doğrulama gerektirmeyen herkese açık bir uç nokta. Müşteriye gösterilecek tüm birim fiyatlar data.catalog.meta içindedir (dizeler):

Fiyatlar arka ofisten ayarlanır, bu yüzden istemcide sabit yazmak yerine canlı okuyun. Cover'ın gerçek ücreti = voice_generation_price × (max_mode doğruysa ayrıca max_mode_factor).

10. Sınırlar ve uyarılar

1. Yükleme boyutu: ≤ 10 MB (sunucu daha fazlasını kabul eder ama giriş ağ geçidi 10 MiB'da büyük gövdeleri keser ve bu "Suno reddetti" gibi görünür; kendi tarafınızda önce engelleyin).
2. Örnek süresi: en az 6 sn, 10–60 sn önerilir; çok kısa olursa platform reddeder.
3. Örnek içeriği: temiz vokal; mevcut bir kayda çok benzeyen her şeyden kaçının (katalog karşılaştırması reddeder).
4. Metin sınırları: lyrics ≤ 3000 karakter; style_requirements / negative_tags / title için sırasıyla 1000 / 1000 / 100 karakter önerilir (stil ve cover gereksinimleri prompt'a eklenir, toplamı 3000 karakterin altında tutun).
5. Şarkı sözü yeniden yazılmaz: ne verirseniz o söylenir (karakter karakter), yerel kısaltma yapılmaz.
6. Her şarkı 2 kayıt üretir; tek sonuç varsaymayın.
7. Kaynak ses kalıcı olarak saklanır: sesi silmek kaynak sesi temizlemez; bu, sonraki cover'ları mümkün ve uyumu izlenebilir tutar.
8. Ses ready olmalı: processing durumundaki bir ses cover'da kullanılamaz.
9. İstek zaman aşımı: soğuk hesapta ilk gönderim ölçümlerde yaklaşık 4,5 dakikaya kadar sürdü, istemci zaman aşımını ≥ 6 dakika yapın. Cover'lar istek düzeyinde tekilleştirme yapmaz, bu yüzden zaman aşımından sonra yeni bir şarkının çıkıp çıkmadığını kontrol edip (§1.5) yeniden göndermeye karar verin.
10. Ses sahipliği: sesler onu oluşturana aittir; cover yalnızca hazır ve silinmemiş sesleri kabul eder. Var olmayan, silinmiş veya başka bir hesaba ait ses 400 döner: bu ses yok veya silinmiş (voice_id=…).

11. Sık sorulan sorular (FAQ)

S1. Ses oluşturmak para tutar mı? Normal oluşturma ve "mevcut sesten oluşturma" ücretsizdir; yalnızca cover'lar (1,2 ¥ / MAX 2,4 ¥) ve güçlendirilmiş klonlar (varsayılan 10 ¥) ücretlidir.

S2. Eşlikli bitmiş bir şarkıyı örnek olarak kullanabilir miyim? Önerilmez. Müzik içeren veya katalogdaki mevcut bir kayda çok benzeyen her şeyi platform reddeder (This audio matches an existing recording in our catalog.). Saf vokal, kuru bir kayıt kullanın.

S3. Cover gönderdikten sonra audio_url neden boş? Gönderim yalnızca kabul edildiği anlamına gelir ve status hâlâ processingtir. Oynatılabilir/indirilebilir adres ancak /api/music/query ile status=completed olana kadar yoklandığında çıkar.

S4. Senaryo B'de (song_clip_id yok) şarkı sözü göndermeli miyim? İsteğe bağlı. Belirli bir içeriği söyletmek için lyrics gönderin; göndermezseniz model kendi halleder ama denetim azalır.

S5. Müşterinin yüklediği ses doğrudan ses olarak kullanılabilir mi? Evet: create'in file_url biçimiyle ya da önce şarkı olarak yükleyip sonra create-from-clip çağırarak.

S6. Başarısızlıkta para iade edilir mi? Doğrudan reddedilen istek (hatalı parametre / platform hatası) ölçümlerde ücretlendirilmez; kabul edilip sonunda başarısız olan görev peşin alınan tutarı geri verir. Nihai başarısızlıkta görev status=failed ve error_message döndürür.

S7. Sesi sildikten sonra onunla üretilmiş şarkıları dinleyebilir miyim? Evet. Silme yalnızca o sesin yeni cover'larda kullanılabilirliğini etkiler.

S8. Bir seferde ne kadar uzun bir şarkıyı cover'layabilirim? duration 1–480 saniye kabul eder; göndermezseniz platform orijinal şarkıya / malzemeye göre karar verir. Dikkat: platformun bitmiş kayıtları en az yaklaşık 30 saniyedir; 30 saniyenin altında bir değer verildiğinde ölçümlerde yine 29,96 / 29,76 saniye çıktı.

Ek A: tam örnek (Node.js, yoklama ve indirme dâhil)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① Ses oluştur (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② Cover'la
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "yavaş folk, akustik gitar",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ Bitene kadar yokla (5 saniyede bir, en fazla 15 dakika)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // çıplak dizi
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ İndir
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "Sesim");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\nsoz…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

Ek B: değişiklik günlüğü