Şarkı sözü zaman damgası kalibrasyon API'si

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

Bu ses tanıma değildir. Metin her zaman sizin verdiğiniz orijinal sözleri kullanır; biz yalnızca her karakteri doğru ana yerleştiririz — yani "yanlış duyulan karakterlerin sözleri kaydırması" diye bir şey olmaz.

Uç nokta açıklaması

Mevcut sözleri sesle hizalar ve satır + karakter bazında zaman damgaları döndürür: karaoke karakter vurgusu, kayan söz ve altyazı üretimi için.

Uç nokta: POST /api/music/lyrics-align

Kimlik doğrulama: Kimlik doğrulama sayfasına bakın; başlık Authorization: Bearer YOUR_API_KEY

Faturalama: çağrı başına (şu anda varsayılan çağrı başına 0,1 ¥); platform şarkısında vokal ayrıştırma işaretliyse platformun "vokal/eşlik ayrıştırma" fiyatı bir kez daha alınır. Gerçekte tahsil edilen tutar güncel arka ofis fiyat yapılandırmasına göre belirlenir.

Ortalama süre: 5–15 saniye (sesin uzunluğuna ve vokalin yerinde ayrıştırılması gerekip gerekmediğine göre)

Kalibrasyon neden gerekli: üretim tarafındaki zaman damgaları her zaman doğru değil

Zaman damgalı şarkı sözü API'si üretim tarafının kelime bazlı zaman damgalarını doğrudan döndürür ve bunlar hatalıdır:

• tekrarlar, yoğun armoniler, rap ve uzun notalarda genel kayma ya da tek karakter kayması sık görülür;
• bazı şarkıların başında bir bölüm eksiktir (örneğin saf giriş; ilk parça ancak on beşinci saniyede başlar);
• bazı satırları net bir zaman çapasına bağlamak zordur.

Kalibrasyon, zaman hizalamasını kendi verdiğiniz sözler üzerinden yeniden yapar: yalnızca zaman düzeltilir, metin asla, bu da "tam oturuyor mu" sorusunun önemli olduğu durumlara uygundur (KTV karakter vurgusu, karakter bazlı altyazı, eşlik ederek söyleme puanlaması).

Önerilen yöntem (üç adım, en iyi sonuç)

1. Önce saf vokali ayırın (vokal/eşlik ayrıştırma) ve yalnızca vokal kanalı hizalayın — eşlik ve armoniler artık karışmaz. Ölçüm dayanağı: aynı şarkının "tam mix vs vokal kanalı" satır satır karşılaştırmasında 28 satırın 5'i 0,25 saniyeden fazla farklıydı (en büyüğü 2,64 saniye); iki bağımsız motor vokal kanalında ortalama 0,239 saniye, tam mixta 0,508 saniye farklıydı — uyum neredeyse yarı yarıya. Bu yüzden karakter vurgusu (KTV/altyazı) için açmanız önerilir. (Kazancın tam ölçüsü yeni motorla yeniden ölçülüyor.)
2. Tam sözleri verin: şarkının tamamı, satır satır, sesle bire bir. Eksik bir cümle ya da bölüm sonraki tüm satırları kaydırır; sözlere [00:23.82] gibi zaman damgaları yazmayın (otomatik yok sayılır).
3. Platform şarkısında vocal_separate: true yeterlidir; "ayrıştırma + hizalama" tek adımda yapılır.

Üç kullanım biçimi

Parametrelerin ilişkisi (en çok burada hata yapılır, dikkatle okuyun)

• song_id gönderirseniz → platform şarkısı yolu: lyrics / audio_url / audio_object_key alanlarını ayrıca göndermeyin;
• audio_url veya audio_object_key gönderirseniz → harici şarkı yolu: ikisinden yalnızca biri, ve song_id göndermeyin;
• vocal_separate yalnızca platform şarkılarında geçerlidir; harici şarkıda gönderilirse reddedilir (ses bizde olmadığı için ayrıştırılamaz).

Yeni: yerel dosyayı doğrudan yükleme (ses bizim sunucularımızdan geçmez)

Ses kendi makinenizdeyse ve önce kendi genel depolamanıza yüklemek istemiyorsanız bunu kullanın. İki adım:

1. POST /api/music/lyrics-align/upload-ticket çağrısını file_name / file_size / content_type ile yapın; put_url (uzun ömürlü kimlik bilgisi içermeyen imzalı URL) ve object_key alırsınız;
2. Dosyayı put_url adresine PUT ile gönderin ve yanıttaki content_type değerini aynen taşıyın (imzaya dahildir; tek karakter değişirse 403 alırsınız);
3. Hizalamayı gönderirken audio_url yerine audio_object_key verin.

Kimlik bilgisi tek kullanımlıktır: hizalama bitince (başarılı ya da başarısız) sunucu nesneyi siler ve aynı anahtarı yeniden kullanmak hata verir.

Yeni: sözler artık zorunlu değil

Eskiden harici şarkıda söz zorunluydu. Artık vermeyebilirsiniz: sunucu önce bir tanıma yapar ve tanınan metni söz olarak kullanır.

Bedelini açıkça söylemek gerekir: metin artık tanıma sonucuna bağlıdır, tek karakterler yanlış olabilir. Bu yanıtlar lyrics_source: "asr", confidence: "low" ile ve warnings[] içinde {"code":"no_reference_lyrics"} ile işaretlenir.

Karakter vurgusu / KTV için mutlaka orijinal sözleri verin.

İstek parametreleri

Headers

Gövde parametreleri

Sınırlar

İstek örnekleri

Harici şarkı (sözler + ses adresi)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "lyrics": "Soğuk sokaklarda yürüyorum\nGece rüzgârı gözlerimi okşuyor\nZaman su gibi akıyor",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

Platform şarkısı (ayrıştırma yok)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "17e52af7-b5df-4877-a98a-dce94e0e6aa2"}'

Platform şarkısı + vokal ayrıştırma (karaoke için önerilir)

curl -X POST https://www.suno-api.io/api/music/lyrics-align \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "17e52af7-b5df-4877-a98a-dce94e0e6aa2", "vocal_separate": true}'

Yanıt

Başarılı yanıt

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "Soğuk sokaklarda yürüyorum",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "S", "start": 21.66, "end": 21.74, "word": true},
        {"char": "o", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

Alan açıklamaları

coverage nasıl kullanılır (üç kademe)

Durum ve süreler

Sunucuda tek çalıştırma sınırı 8 dakikadır; istemci zaman aşımını 120 saniye veya üzerine ayarlayın.

Hata yanıtları

{
  "success": false,
  "message": "音频超过 6 分钟上限（实际 7.2 分钟）"
}

İlke: nihai sonuç yoksa tam iade. Ücret yalnızca karakter zaman damgaları gerçekten döndüğünde alınır ve iade otomatiktir, başvuru gerekmez.

Faturalama

Birleşim:

ödenecek = temel fiyat + (söz verilmedi ? deşifre ek ücreti : 0) + (ayrıştırma işaretli ? ayrıştırma fiyatı : 0)

Vokal ayrıştırma ücreti yalnızca bir kez alınır: şarkıyı zaten ayrıştırdıysanız ve vokal kanalı doğrudan varsa bunu bu uç nokta alır; yerinde ayrıştırma gerekiyorsa ayrıştırma adımı alır.

Tam örnek (Python)

import requests

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

def align_lyrics(song_id=None, lyrics=None, audio_url=None, vocal_separate=False):
    payload = {}
    if song_id:
        payload["song_id"] = song_id
        payload["vocal_separate"] = vocal_separate
    else:
        payload["lyrics"] = lyrics
        payload["audio_url"] = audio_url

    r = requests.post(
        f"{BASE}/api/music/lyrics-align",
        headers={"Authorization": f"Bearer {API_KEY}"},
        json=payload,
        timeout=600,
    )
    data = r.json()
    if not data.get("success"):
        raise RuntimeError(data.get("message"))
    return data


res = align_lyrics(song_id="17e52af7-b5df-4877-a98a-dce94e0e6aa2", vocal_separate=True)
print("hizalama kalitesi coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # karakter karaokesi: line["chars"] içindeki her karakterin kendi start / end değeri var

Sık sorulan sorular

S: Çıktı karakter bazlı mı satır bazlı mı? C: İkisi de. lines[].start satır bazlı, lines[].chars[].start / end karakter bazlıdır; oynatıcı hangisi gerekiyorsa onu kullanır.

S: Dönen metin neden gönderdiğimle birebir aynı? C: Tasarım gereği. Tanıyıp yeniden yazmıyoruz, yalnızca zamanı hizalıyoruz; sözler asla "yazım hatasına düzeltilmez".

S: coverage yüksek ama yine de biraz kaymış duyuluyor. C: Karakter hizalama hatası genelde onlarca milisaniye düzeyindedir; tüm şarkı sabit bir miktar kaymışsa büyük olasılıkla sesin başında bir sessizlik vardır; kırpıp yeniden deneyin.

S: Az önce ayrıştırma çalışıyordu, şimdi "vokal kanalı kullanılamıyor" diyor. C: Ayrıştırma sonuçları kısa ömürlü geçici adreslerdir (ölçüm: yaklaşık yarım saat sonra geçersiz olur). Bu durumda uç nokta otomatik olarak yeniden ayrıştırmayı dener; yine başarısız olursa tam iade yapılır. Yani "şimdi ayrıştır, sonra kalibre et" güvenilir değil; ikisini aynı akışta yapın.

S: Platform şarkısını kendim mi ayrıştırmalıyım? C: Hayır. vocal_separate: true ile şarkıda zaten vokal kanalı var mı diye bakarız; kullanılabilir kanal yoksa hata verip iade ederiz, tam mixi geçiştirmeyiz.

S: Toplu yapılabilir mi? C: İstek başına bir şarkı. Toplu için döngü kurun; her çağrı normal faturalanır, sonuçları yerelde önbelleklemeniz önerilir.

S: Sonuç kaydediliyor mu? C: Bu uç nokta hiçbir şey kaydetmez; dönen değeri kendiniz saklayın (satır ve karakter zaman damgaları yanıttadır).