Şarkı sorgulama ve geçmiş API'si

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

Bu sayfa üç ücretsiz sorgu uç noktasını kapsar:

Bir üretim uç noktasında kabul makbuzu modunu (accept_mode=async) kullandıysanız elinizde şarkı ID'si değil makbuz numarası vardır. İlerlemeyi GET /api/music/requests/{request_id} ile takip edin ve gerçek song_id'yi aldıktan sonra bu sayfadaki uç noktalara dönün. Basit mod üretim API'si sayfasındaki "Kabul makbuzu modu" bölümüne bakın.

Kimlik doğrulama ve veri kapsamı

Üç uç nokta da aynı API anahtarıyla kimlik doğrular:

Authorization: Bearer YOUR_API_KEY

Şarkı geçmişi, API anahtarının ait olduğu user_id'ye göre yalıtılır. Aynı ana hesap altında oluşturulan birden çok API anahtarı o hesabın geçmişini okuyabilir, ancak başka bir kullanıcının veya alt site hesabının şarkılarını okuyamaz.

Geçmiş uç noktaları yalnızca gerçekten üretilmiş şarkıları döndürür. Şunlar hariçtir:

• pending: ile başlayan üretim yer tutucu kayıtları;
• kaynak ses yüklemeleri ve güçlendirilmiş yükleme kayıtları;
• vokal/akompaniman ayrımı ve stem'ler gibi alt sonuçlar;
• başka kullanıcıların veya alt site hesaplarının şarkıları.

1. Üretim durumunu sorgulama

Bir veya birkaç şarkı ID'sinin geçerli durumunu ve nihai sonucunu sorgular.

Uç nokta: POST /api/music/query

Faturalama: Ücretsiz.

Headers

Gövde parametreleri

Örnek istek

curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "song_ids": "clip_id_1,clip_id_2"
  }'

Örnek yanıt

[
  {
    "song_id": "clip_id_1",
    "song_title": "Şarkı başlığı",
    "status": "completed",
    "audio_url": "https://example.com/audio.mp3",
    "video_url": "https://example.com/video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "lyrics": "Şarkı sözleri",
    "style_tags": "Mandopop, acoustic",
    "duration": 180.5,
    "model_version": "suno-v6",
    "created_at": "2026-05-21T10:00:00Z"
  }
]

Uyumluluk notları

Eski belgeler song_ids'i dizi olarak gösterebilir. Bugün virgülle ayrılmış dize önerilir; uç nokta gerçekte böyle çağrılır.

song_ids gerçek şarkı ID'leri içermelidir. pending: ile başlayan yer tutucu ID nihai song_id değildir ve burada kullanılamaz; yalnızca yer tutucu ID'ler sorgulanırsa boş bir dizi [] dönebilir.

Yanıttaki model, model_version veya platform model_name geçmiş değerleri koruyabilir. Yeni görevler suno-v6, suno-v6-wild veya suno-v6-mini kullanmalıdır; suno-v2'den suno-v5-5'e kadar olanlar kullanımdan kaldırıldı ve geçmişte bu adları görmek modelin hâlâ gönderilebileceği anlamına gelmez.

Bir görev pending, submitted veya processing durumundayken audio_url, video_url ve cover_url boş olabilir — bu, tamamlanmamış bir görev için normaldir. Yalnızca adresin boş olmasından hata sonucu çıkarmayın; status alanına bakın ve durum tamamlandığında yeniden sorgulayın. Ancak durum tamamlanmış ve adresler hâlâ boşsa song_id ile destek ekibine başvurmanız önerilir.

⚠️ Ses adresleri 7 gün yaşar — dosyalarınızı zamanında taşıyın

Burada dönen audio_url, video_url (ve WAV gibi diğer medya adresleri) platformun nesne depolamasından sunulur ve varsayılan olarak 7 gün sonra geçersiz olur: dosyalar geri dönüştürülür ve eski adres 404 döner.

• Bu 7 gün içinde dosyaları kendi depolamanıza taşıyın; adresi uzun ömürlü bir bağlantı olarak görmeyin.
• Süresi geçmiş bir adres şarkıyı yeniden üretmeyi gerektirmez ve yeniden ücretlendirilmez: o şarkı için yeni ve geçerli bir adres almak üzere bu uç noktayı (POST /api/music/query) yeniden çağırın.

2. Hesabın şarkı geçmişini sorgulama

Geçerli API anahtarının ait olduğu ana hesabın ürettiği şarkıları listeler. Kendi şarkı listenizi, seçicinizi veya geçmiş sayfanızı kurmak için uygundur.

Uç nokta: GET /api/music/songs

Faturalama: Ücretsiz.

Sorgu parametreleri

Sonuçlar created_at ve iç kayıt ID'sine göre azalan sırada dizilir; sayfalama sırası böylece sabit kalır.

Zaman aşımına uğrayan bir gönderimi bulma: üretim uç noktaları kabulden önce ara yanıt vermez. Gönderim sırasında istemciniz zaman aşımına uğradıysa veya bağlantı koptuysa, o sipariş kabul edilmiş ve üretiliyor olabilir. Bu uç noktaya bakın (en yeniler önce): kabul edilen şarkılar listede normal şekilde görünür. Gerçekten olmadığını doğruladıktan sonra yeniden gönderin; aksi halde iki kez ödeme yaparsınız. Yeni API genel bakışı sayfasındaki "Bekleme süreleri ve zaman aşımı ayarları" bölümüne bakın.

Örnek istek

curl "https://www.suno-api.io/api/music/songs?p=1&page_size=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

Örnek yanıt

{
  "success": true,
  "message": "",
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "8e31b3c0-example-song-id",
        "title": "Gecedeki şehir",
        "status": "completed",
        "generation_type": "custom_generate",
        "model": "suno-v6",
        "duration": 187.42,
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "created_at": 1784000000,
        "completed_at": 1784000120
      }
    ]
  }
}

Yanıt alanları

Liste uç noktası prompt, faturalama alanı, hesap bilgisi veya ham yanıt döndürmez. Prompt ve üretim parametreleri için şarkı ayrıntı uç noktasını çağırın.

3. Üretim parametrelerini sorgulama

Şarkı ID'sinden, üretim sırasında platformun sakladığı prompt, stil, model ve kaynak şarkı gibi parametreleri sorgular.

Uç nokta: GET /api/music/songs/:song_id

Faturalama: Ücretsiz.

Yalnızca geçerli API anahtarının ait olduğu ana hesabın şarkıları okunabilir. Başka kullanıcıların veya alt site hesaplarının şarkıları tek biçimde "şarkı bulunamadı" olarak ele alınır.

Yol parametresi

Örnek istek

curl "https://www.suno-api.io/api/music/songs/8e31b3c0-example-song-id" \
  -H "Authorization: Bearer YOUR_API_KEY"

Örnek yanıt

{
  "success": true,
  "message": "",
  "data": {
    "song_id": "8e31b3c0-example-song-id",
    "title": "Gecedeki şehir",
    "status": "completed",
    "generation_type": "custom_generate",
    "model": "suno-v6",
    "duration": 187.42,
    "audio_url": "https://example.com/audio.mp3",
    "image_url": "https://example.com/cover.jpg",
    "video_url": "",
    "wav_url": "",
    "created_at": 1784000000,
    "completed_at": 1784000120,
    "client_request_id": "example-request-id",
    "client_request_index": 0,
    "parameters": {
      "prompt": "yağmur sonrası şehir sokakları, yeniden buluşma üzerine sözler",
      "style_tags": "Mandopop, acoustic, warm vocal",
      "title": "Gecedeki şehir",
      "model": "suno-v6",
      "generation_type": "custom_generate",
      "source_song_id": "",
      "source_audio_url": "",
      "custom_mode": null,
      "instrumental": null,
      "negative_tags": null,
      "vocal_gender": null,
      "lyrics_mode": null,
      "wait_audio": null,
      "style_weight": null,
      "weirdness_constraint": null
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": [
        "suno_tasks"
      ],
      "unavailable_fields": [
        "custom_mode",
        "instrumental",
        "negative_tags",
        "vocal_gender",
        "lyrics_mode",
        "wait_audio",
        "style_weight",
        "weirdness_constraint"
      ]
    }
  }
}

parameters alanları

prompt_view alanı (prompt görüntüleme, 2026-09-28'de eklendi)

prompt_view, "prompt görüntüleme" için ayrılmış normalleştirilmiş bir yapıdır: verileri üretim türüne göre sabit bölümlere ayırır, böylece istemci hangi alanı göstereceğine kendisi karar vermek zorunda kalmaz. Tamamen ek bir alandır — eski alanlar (parameters, parameter_retention) adını ve anlamını korur ve yeni alanı ayrıştırmayan istemciler hiçbir şekilde etkilenmez.

"prompt_view": {
  "type": "custom_generate",
  "type_label": "Özel mod",
  "generation": {
    "model": "suno-v6", "max_mode": false, "duration": 182.4,
    "title": "Sabahın dördü#701f37", "title_base": "Sabahın dördü", "title_suffix": "701f37",
    "created_at": 1790421721
  },
  "inputs": {
    "user_text": "...", "user_text_kind": "lyrics",
    "user_style": "guochao elektronik, derin sub bas, retro synth",
    "style_tags": "guochao elektronik, derin sub bas, retro synth",
    "style_source": "user", "lyrics": "...",
    "negative_tags": "", "is_instrumental": false
  },
  "extended": {
    "vocal_gender": "m", "style_weight": 0.5, "audio_weight": 0.85,
    "weirdness_constraint": 0.5, "variety": 2, "lyrics_mode": "manual",
    "custom_mode": true
  },
  "reference": { "voice_name": "sv_40_34", "source_song_id": "", "source_title": "" },
  "retention": {
    "recorded_since": "2026-09-28", "missing_reason": "",
    "not_applicable_fields": ["audio_weight"]
  }
}

extended içinde görünebilecek alanlar: vocal_gender, style_weight, audio_weight, weirdness_constraint, variety, lyrics_mode, custom_mode ve ses efekti grubu sound_type / sound_bpm / sound_key / sound_loop. Boş değerler hiçbir zaman döndürülmez.

Üç gösterim kuralı (tahmin etmek yerine bunlara uyun):

1. Stilin kaynağını ayırt edin: style_source=suno_derived olduğunda "stil (Suno tarafından açıklamanızdan çıkarıldı)" olarak gösterin, "sizin stiliniz" diye yazmayın;
2. Dahili promptlar hiç görünmez: ses cover türleri yalnızca kullanıcının yazdığı 【stil gereksinimleri】/【cover gereksinimleri】 döndürür; model için birleştirdiğimiz sabit yapı hiçbir alanda görünmez (geçmiş veriler de aynı şekilde temizlenmiştir);
3. Saklanmayan parametreleri tahmin etmeyin: extended içinde yoksa o zaman kaydedilmemiştir — nedeni retention ile açıklayın.

Parametre saklama notları

parameter_retention, "açıkça boş bir değer iletildi" ile "alan geçmişte hiç saklanmadı" durumlarını ayırmak için vardır:

• core_parameters_available: ana görev kaydı var mı; geçerli bir ayrıntı sorgusunda normalde true;
• extended_parameters_available: ilgili genişletilmiş müzik görevi kaydı bulundu mu;
• sources: bu yanıtın hangi veri tablolarından geldiği;
• unavailable_fields: geçmiş verilerden güvenilir şekilde kurtarılamayan alanlar; bunlar parameters içinde null döner.

Sıradan geçmiş şarkılar genelde prompt, stil, güncel başlık, model, üretim türü ve kaynak şarkıyı sakladı, ancak tüm gelişmiş parametreleri ayrı ayrı saklamadı. Platform eksik değerleri generation_type üzerinden asla tahmin etmez.

Bazı genişletilmiş müzik görevleri ayrıca orijinal prompt, stil, başlık, model ve ek olarak custom_mode, negative_tags, vocal_gender, style_weight ve weirdness_constraint sakladı. Genişletilmiş kayıt olsa bile instrumental, lyrics_mode ve wait_audio kurtarılamayabilir.

Başlıklar sonradan kullanıcı tarafından değiştirilebilir. Sıradan bir geçmiş görevi ayrı bir orijinal başlık saklamadıysa parameters.title güncel başlık olabilir; genişletilmiş görev kaydı varsa orada saklanan orijinal üretim başlığı tercih edilir.

Bulunamadı veya yetki yok

İş hataları tek biçimli bir yanıt zarfı kullanır. Şarkı yoksa veya geçerli hesaba ait değilse şu döner:

{
  "success": false,
  "message": "song not found"
}

Bu iş hatası şu anda HTTP 200 ile döner; sonucu success alanına göre değerlendirin. Eksik, geçersiz, süresi dolmuş veya devre dışı bırakılmış API anahtarı HTTP 401 döndürür.

Güvenlik notları

Geçmiş ve ayrıntı uç noktaları şunları asla döndürmez:

• API anahtarları veya token ID'leri;
• kota, faturalama veya iade alanları;
• hesap bilgileri veya ham yanıtlar;
• nesne depolamasının dahili anahtarları;
• yönetici hataları veya dahili kaynak hataları.