Şarkı medyası indirme ve önizleme API'si

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

Uç nokta açıklaması

Bu uç nokta grubu "medya adresi alma" ile "dosyayı gerçekten indirme" işlerini ayırır:

• Doğrudan oynatabileceğiniz veya indirebileceğiniz bir adres için (örneğin kendi oynatıcınıza koymak ya da nesne depolamaya kopyalamak): POST /api/music/download-url veya yanıtlarda zaten verilen GET /api/music/download kullanın.
• Tarayıcının dosyayı doğrudan diske kaydetmesi için: POST /api/music/download-file (tek dosya) veya POST /api/music/download-all (paket) kullanın.
• Şarkı hâlâ üretiliyor ve önce dinlemek istiyorsanız: POST /api/music/generation-stream-url kullanın.

Faturalama: Hepsi ücretsizdir. İndirme ve önizleme yalnızca platformun zaten barındırdığı medyayı okur; Suno'yu çağırmaz ve ücret alınmaz.

Önerilen model: suno-v6. suno-v6, suno-v6-wild veya suno-v6-mini kullanılabilir.

Kimlik doğrulama

Desteklenen medya türleri (kind)

1) Medya adresi alma

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": "song_id", "kind": "song"}'

{
  "code": 200,
  "message": "success",
  "data": {
    "song_id": "song_id",
    "kind": "song",
    "url": "https://media.suno-api.io/assets/song_id-mp3.mp3",
    "nav_url": "https://media.suno-api.io/assets/song_id-mp3.mp3?...&response-content-disposition=attachment..."
  }
}

url oynatma veya kendiniz kopyalayıp saklama içindir; nav_url Content-Disposition: attachment taşır ve tarayıcı adres çubuğuna doğrudan yapıştırıp indirmek için uygundur (bazı mobil tarayıcılar blob indirmeyi desteklemediğinde kullanın).

⚠️ Adres geçerliliği: 7 gün — dosyayı zamanında kopyalayın

url / nav_url platformun nesne depolamasına işaret eder ve varsayılan olarak 7 gün sonra geçersiz olur (dosyalar geri alınır ve eski adres 404 döndürür). Bu 7 gün içinde kendi depolamanıza kopyalayın.

Süre dolduktan sonra şarkıyı yeniden üretmeniz gerekmez: POST /api/music/download-url çağrısını yeniden yapın (veya refresh: true gönderin) ve o şarkı için yeni ve geçerli adresler alın. Bu uç nokta grubu ücretsizdir ve ek ücret doğurmaz.

2) Tek dosyayı doğrudan indirme

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id", "kind": "song"}' \
  -o song.mp3

Yanıt gövdesi bir dosya akışıdır (JSON değil) ve Content-Disposition dosya adını zaten taşır. Şarkı sözü ve zaman damgalı sözler yalnızca bu uç nokta ile alınır (download-url yalnızca medya adresi döndürür, söz döndürmez). .lrc dosyası şu an yalnızca bazı şarkılarda desteklenir; success:false dönerse bir sonraki bölümdeki Zaman damgalı şarkı sözü API'si yöntemiyle .lrc dosyasını kendiniz oluşturun, yeniden denemeyin.

Zaman damgalı sözler (.lrc) nasıl alınır

Her şarkıda çalışan iki adım önerilir:

1. adım: kelime bazlı zaman çizelgesini alın (ücretsiz)

curl -X POST https://www.suno-api.io/api/lyrics/timeline \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "suno-v6", "song_id": "song_id"}'

Dönen değer doğrudan bir dizidir (data sarmalayıcısı yoktur); her öğe şöyle görünür: {"word": "…", "start_s": 1.117, "end_s": 8.138, "success": true, "p_align": 0.99}. word zaten satır sonları içerir, satırlara bölebilirsiniz; alan anlamları, enstrümantal bölümleri filtreleme ve diğer uyarılar için Zaman damgalı şarkı sözü API'si sayfasındaki "Alanlar" ve "Kullanım notları" bölümlerine bakın.

2. adım: start_s ile .lrc dosyasını kendiniz oluşturun (zaman biçimi [mm:ss.cc])

def to_lrc(segments):
    lines = []
    for seg in segments:
        text = seg["word"].strip()
        if not text:
            continue
        start = max(0.0, float(seg["start_s"]))
        cs = int(start * 100 + 0.5)
        lines.append(f"[{cs // 6000:02d}:{(cs % 6000) // 100:02d}.{cs % 100:02d}]{text}")
    return "\n".join(lines)

GET /api/music/download?song_id=<id>&kind=lrc sunucunun ürettiği .lrc dosyasını da doğrudan indirir, ancak şu an yalnızca bazı şarkılar desteklenir: success:false dönerse yukarıdaki yöntemle kendiniz oluşturun — yeniden denemeye gerek yoktur ve faturalamayı etkilemez.

3) Toplu indirme

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}' \
  -o songs.zip

song_id (tek) veya song_ids (toplu, en fazla 50 kayıt) kullanın. Yanıt gövdesi bir ZIP akışıdır.

4) Sabit indirme adresi

GET /api/music/download?song_id=<id>&kind=<kind>, şarkı yanıtlarında doğrudan verilen indirme girişidir. Hem API anahtarını hem oturum açma durumunu kabul eder, download-file ile aynı davranır ve istemciye ya da üçüncü taraf bir oynatıcıya sabit olarak gömülmeye uygundur.

5) Üretim sırasında önizleme

curl -X POST https://www.suno-api.io/api/music/generation-stream-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_ids": ["song_id_1", "song_id_2"]}'

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "song_id": "song_id_1",
        "url": "https://media.suno-api.io/assets/song_id_1-mp3.mp3",
        "expires_at": 0,
        "content_type": "audio/mpeg",
        "playable_until_completed": false,
        "mode": "mp3",
        "ranges": true
      }
    ]
  }
}

playable_until_completed değerinin true olması, bunun üretimi süren bir şarkı için geçici önizleme adresi olduğunu gösterir; şarkı tamamlanınca kalıcı adrese geçin. Bir şarkı başarısız olursa o öğe bir error alanı taşır, diğer şarkılar normal şekilde döner.

Notlar

• Tüm uç noktalar yalnızca platformun barındırdığı medya adreslerini döndürür; Suno'nun şifreli kaynağını veya geçici imzalı bir adresi asla döndürmez.
• Adresler kalıcı değildir; uzun süre saklamak istiyorsanız dosyaları kendiniz kopyalayın. Özgün dosyayı diske kaydetmeniz gerektiğinde download-file kullanın.
• Bir kanalın MIDI'si için o kanalın ayrıştırmasının tamamlanmış olması gerekir, aksi halde hata döner.