API voor het kalibreren van tijdstempels van songteksten

Bijgewerkt op 2026-09-18 · Suno-API-team

Dit is geen spraakherkenning. De tekst gebruikt altijd de originele songtekst die u aanlevert; wij zetten alleen elk teken op het juiste moment — dus "verkeerd gehoorde tekens die de tekst laten verschuiven" gebeurt nooit.

Beschrijving van het endpoint

Het lijnt bestaande songtekst uit op audio en levert tijdstempels per regel en per teken — voor teken-voor-teken markering zoals karaoke, meescrollende tekst en ondertitelgeneratie.

Endpoint: POST /api/music/lyrics-align

Authenticatie: zie Authenticatie; de header is Authorization: Bearer YOUR_API_KEY

Facturering: per aanroep (momenteel standaard 0,1 ¥ per aanroep); staat bij een nummer van het platform de stemseparatie aangevinkt, dan wordt nog één keer het platformtarief "stem/begeleiding scheiden" gerekend. Het werkelijk gefactureerde bedrag volgt de prijsconfiguratie in de back-office.

Gemiddelde duur: 5–15 seconden (afhankelijk van de audiolengte en of de stem ter plaatse gescheiden moet worden)

Waarom kalibreren nodig is: tijdstempels van de generatiekant zijn niet altijd nauwkeurig

De API voor songteksten met tijdstempels geeft de tijdstempels per woord rechtstreeks van de generatiekant terug, en die zijn niet nauwkeurig:

• reprises, dichte harmonieën, rap en lange tonen wijken vaak in hun geheel af of verschuiven losse tekens;
• bij sommige nummers ontbreekt een stuk aan het begin (bijvoorbeeld een pure intro, waarbij het eerste fragment pas rond de vijftien seconden begint);
• sommige regels zijn moeilijk aan een duidelijk tijdsanker te koppelen.

De kalibratie doet de tijduitlijning opnieuw op basis van de songtekst die u zelf aanlevert: alleen de tijd wordt gecorrigeerd, nooit de tekst — geschikt voor situaties waarin "klopt het precies" telt (tekenmarkering als in KTV, ondertitels per teken, meezingbeoordeling).

Aanbevolen aanpak (drie stappen, beste resultaat)

1. Isoleer eerst de stem (stem/begeleiding scheiden) en lijn alleen het stemspoor uit — begeleiding en harmonieën storen dan niet meer. Meetbasis: bij een regel-voor-regelvergelijking "volledige mix vs stemspoor" van hetzelfde nummer verschilden 5 van de 28 regels meer dan 0,25 s (de grootste 2,64 s); twee onafhankelijke engines verschilden gemiddeld 0,239 s op het stemspoor en 0,508 s op de volledige mix — bijna half zoveel overeenstemming. Voor tekenmarkering (KTV/ondertitels) is aanzetten dus aan te raden. (De exacte winst wordt opnieuw gemeten met de nieuwe engine.)
2. Lever de volledige songtekst: het hele nummer, regel voor regel, één op één met de audio. Een ontbrekende zin of sectie verschuift alle volgende regels; zet geen tijdstempels zoals [00:23.82] in de tekst (die worden automatisch genegeerd).
3. Bij een nummer van het platform volstaat vocal_separate: true en doen wij "scheiden + uitlijnen" in één stap.

Drie manieren om het te gebruiken

Hoe de parameters samenhangen (hier gaat het het vaakst mis — lees goed)

• song_id sturen → route nummer van het platform: stuur niet ook lyrics / audio_url / audio_object_key;
• audio_url of audio_object_key sturen → route extern nummer: slechts één van de twee, en geen song_id;
• vocal_separate werkt alleen bij nummers van het platform; bij een extern nummer wordt het geweigerd (de audio is niet bij ons, dus niet te scheiden).

Nieuw: directe upload van een lokaal bestand (de audio gaat niet via onze servers)

Gebruik dit als de audio op uw machine staat en u die niet eerst naar uw eigen openbare opslag wilt sturen. Twee stappen:

1. POST /api/music/lyrics-align/upload-ticket met file_name / file_size / content_type en u krijgt een put_url (ondertekende URL zonder langlevende inloggegevens) en een object_key;
2. Doe een PUT van het bestand naar put_url en neem de content_type uit het antwoord ongewijzigd over (die hoort bij de handtekening; één gewijzigd teken geeft 403);
3. Stuur bij het uitlijnen audio_object_key in plaats van audio_url.

De inloggegevens zijn eenmalig: zodra het uitlijnen klaar is (gelukt of mislukt) verwijdert de server het object, en dezelfde sleutel opnieuw gebruiken geeft een fout.

Nieuw: de songtekst is nu optioneel

Vroeger was tekst verplicht bij een extern nummer. Nu mag die ontbreken: de server doet eerst een herkenning en gebruikt de herkende tekst als songtekst.

De keerzijde moet duidelijk zijn: de tekst volgt dan het herkenningsresultaat, dus losse tekens kunnen fout zijn. Zulke antwoorden zijn gemarkeerd met lyrics_source: "asr", confidence: "low" en in warnings[] {"code":"no_reference_lyrics"}.

Voor tekenmarkering / KTV levert u altijd de originele tekst aan.

Verzoekparameters

Headers

Body-parameters

Limieten

Voorbeeldverzoeken

Extern nummer (tekst + audioadres)

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": "Ik loop door koude straten\nDe nachtwind strijkt langs mijn ogen\nDe tijd stroomt als water",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

Nummer van het platform (zonder separatie)

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"}'

Nummer van het platform + stemseparatie (aanbevolen voor karaoke)

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}'

Antwoord

Succesantwoord

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "Ik loop door koude straten",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "I", "start": 21.66, "end": 21.74, "word": true},
        {"char": "k", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

Referentie van velden

Hoe u coverage gebruikt (drie niveaus)

Status en doorlooptijden

De limiet van één serverrun is 8 minuten; zet de client-timeout op 120 seconden of meer.

Foutantwoorden

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

Uitgangspunt: geen eindresultaat betekent volledige terugbetaling. Er wordt pas afgerekend als de tekentijdstempels echt worden teruggegeven, en de terugbetaling gebeurt automatisch, zonder aanvraag.

Facturering

De combinatie:

te betalen = basisprijs + (geen tekst aangeleverd ? transcriptietoeslag : 0) + (separatie aangevinkt ? separatieprijs : 0)

De stemseparatie wordt maar één keer gerekend: hebt u het nummer al gescheiden en is het stemspoor direct beschikbaar, dan rekent dit endpoint het; moet er ter plaatse gescheiden worden, dan rekent de separatiestap het.

Volledig voorbeeld (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("kwaliteit van de uitlijning coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # karaoke per teken: elk teken in line["chars"] heeft eigen start / end

Veelgestelde vragen

V: Is de uitvoer per teken of per regel? A: Beide. lines[].start is per regel, lines[].chars[].start / end per teken; de speler pakt wat nodig is.

V: Waarom is de teruggegeven tekst identiek aan wat ik stuurde? A: Dat is het ontwerp. We herkennen niet en herschrijven niet, we lijnen alleen de tijd uit — de tekst kan dus nooit "in een typefout gecorrigeerd" worden.

V: De coverage is hoog maar het klinkt toch licht verschoven. A: De fout per teken ligt meestal in de orde van tientallen milliseconden; is het hele nummer een vaste hoeveelheid verschoven, dan staat er waarschijnlijk stilte aan het begin van de audio: knip die weg en probeer opnieuw.

V: Waarom werkte de separatie net wel en zegt het nu "stemspoor niet beschikbaar"? A: Separatie-resultaten zijn kortlevende tijdelijke adressen (gemeten: verlopen na ongeveer een half uur). Dan probeert het endpoint automatisch opnieuw te scheiden; lukt dat alsnog niet, dan volgt volledige terugbetaling. "Nu scheiden, later kalibreren" is dus onbetrouwbaar: doe beide in dezelfde flow.

V: Moet ik een nummer van het platform zelf eerst scheiden? A: Nee. Met vocal_separate: true controleren we of het nummer al een stemspoor heeft; is er geen bruikbaar spoor, dan geven we een fout en betalen terug in plaats van de volledige mix door te schuiven.

V: Kan het in batches? A: Eén nummer per verzoek. Voor batches lussen; elke aanroep wordt normaal gefactureerd, dus lokaal cachen is aan te raden.

V: Wordt het resultaat bewaard? A: Dit endpoint bewaart niets; bewaar de teruggegeven waarde zelf (regel- en tekentijdstempels staan in het antwoord).