API för kalibrering av tidsstämplar i låttext

Uppdaterad 2026-09-18 · Suno-API-teamet

Det här är inte taligenkänning. Texten använder alltid den ursprungliga text du anger; vi placerar bara varje tecken vid rätt tidpunkt — så "felhörda tecken som förskjuter texten" kan aldrig hända.

Beskrivning av ändpunkten

Den linjerar befintlig låttext mot ljud och ger tidsstämplar per rad och per tecken — för teckenvis markering som i karaoke, rullande text och undertextgenerering.

Ändpunkt: POST /api/music/lyrics-align

Autentisering: se Autentisering; headern är Authorization: Bearer YOUR_API_KEY

Fakturering: per anrop (för närvarande 0,10 ¥ per anrop som standard); är röstseparering ikryssad på en plattformslåt debiteras plattformens pris "separera sång/komp" en gång till. Det faktiskt debiterade beloppet följer prisinställningen i backoffice.

Genomsnittlig tid: 5–15 sekunder (beroende på ljudets längd och om sången måste separeras på plats)

Varför kalibrering behövs: tidsstämplarna från genereringssidan är inte alltid exakta

API för tidsstämplad låttext returnerar genereringssidans tidsstämplar per ord direkt, och de är oprecisa:

• repriser, täta harmonier, rap och långa toner driver ofta i sin helhet eller förskjuter enstaka tecken;
• vissa låtar saknar ett stycke i början (till exempel ett rent intro, där första fragmentet börjar först efter ett tiotal sekunder);
• en del rader är svåra att ankra vid en tydlig tidpunkt.

Kalibreringen gör tidslinjeringen på nytt utifrån den text du själv anger: bara tiden korrigeras, aldrig texten — det passar fall där "stämmer det" spelar roll (teckenmarkering som i KTV, undertext per tecken, betyg vid medsjungning).

Rekommenderat tillvägagångssätt (tre steg, bäst resultat)

1. Extrahera sången först (separera sång/komp) och linjera bara sångspåret — komp och harmonier stör inte längre. Mätgrund: i en rad-för-rad-jämförelse "fullmix mot sångspår" av samma låt skilde 5 av 28 rader sig mer än 0,25 s (den största 2,64 s); två oberoende motorer skilde sig i snitt 0,239 s på sångspåret och 0,508 s på fullmixen — nästan halva samstämmigheten. För teckenmarkering (KTV/undertext) rekommenderas därför att slå på den. (Den exakta vinsten mäts om med den nya motorn.)
2. Ange hela texten: hela låten, rad för rad, ett-till-ett med ljudet. En saknad mening eller sektion förskjuter alla följande rader; skriv inte in tidsstämplar som [00:23.82] i texten (de ignoreras automatiskt).
3. På en plattformslåt räcker vocal_separate: true, och vi gör "separera + linjera" i ett steg.

Tre sätt att använda den

Hur parametrarna hänger ihop (här blir det oftast fel — läs noga)

• Skickar du song_id → väg för plattformslåt: skicka inte också lyrics / audio_url / audio_object_key;
• Skickar du audio_url eller audio_object_key → väg för extern låt: bara en av dem, och ingen song_id;
• vocal_separate fungerar bara på plattformslåtar; på en extern låt avvisas den (ljudet finns inte hos oss, det går inte att separera).

Nytt: direkt uppladdning av lokal fil (ljudet går inte via våra servrar)

Används när ljudet finns på din maskin och du inte vill lägga det i din egen offentliga lagring först. Två steg:

1. POST /api/music/lyrics-align/upload-ticket med file_name / file_size / content_type och du får en put_url (signerad URL utan långlivade uppgifter) och en object_key;
2. Gör en PUT av filen till put_url och ta med content_type från svaret precis som det är (den ingår i signaturen; ett ändrat tecken ger 403);
3. Skicka audio_object_key i stället för audio_url när du skickar in linjeringen.

Uppgifterna är engångs: när linjeringen är klar (lyckad eller misslyckad) raderar servern objektet, och samma nyckel igen ger ett fel.

Nytt: texten är nu valfri

Tidigare krävde en extern låt text. Nu går det att utelämna den: servern gör först en igenkänning och använder den igenkända texten som låttext.

Priset för det måste sägas rakt ut: texten följer då igenkänningsresultatet, så enstaka tecken kan vara fel. Sådana svar märks med lyrics_source: "asr", confidence: "low" och i warnings[] {"code":"no_reference_lyrics"}.

För teckenmarkering / KTV: ange alltid originaltexten.

Begäransparametrar

Headers

Brödtextparametrar

Gränser

Exempelbegäranden

Extern låt (text + ljudadress)

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": "Jag går genom kalla gator\nNattvinden stryker mina ögon\nTiden rinner som vatten",
    "audio_url": "https://your-bucket.example.com/song.mp3"
  }'

Plattformslåt (utan separering)

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

Plattformslåt + röstseparering (rekommenderas för 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}'

Svar

Lyckat svar

{
  "success": true,
  "lyrics_source": "platform",
  "vocal_separate": false,
  "coverage": 0.935,
  "exact": 196,
  "fuzzy": 4,
  "total": 214,
  "lines": [
    {
      "text": "Jag går genom kalla gator",
      "start": 21.66,
      "end": 24.06,
      "chars": [
        {"char": "J", "start": 21.66, "end": 21.74, "word": true},
        {"char": "a", "start": 21.98, "end": 22.22, "word": true}
      ]
    }
  ]
}

Fältförklaring

Så används coverage (tre nivåer)

Status och tider

Gränsen för en serverkörning är 8 minuter; ställ in klientens timeout på 120 sekunder eller mer.

Felsvar

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

Princip: inget slutresultat innebär full återbetalning. Debitering sker först när teckentidsstämplar faktiskt returneras, och återbetalningen är automatisk, utan ansökan.

Fakturering

Kombinationen:

att betala = baspris + (ingen text angiven ? transkriberingstillägg : 0) + (separering ikryssad ? separeringspris : 0)

Röstsepareringen tas bara ut en gång: har du redan separerat låten och sångspåret finns direkt tar den här ändpunkten ut den; måste separeringen ske på plats tar separeringssteget ut den.

Fullständigt exempel (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("linjeringskvalitet coverage =", res["coverage"])
for line in res["lines"]:
    print(f'{line["start"]:7.2f}  {line["text"]}')
    # tecken-karaoke: varje tecken i line["chars"] har egen start / end

Vanliga frågor

F: Är utdata per tecken eller per rad? S: Båda. lines[].start är per rad, lines[].chars[].start / end per tecken; spelaren tar det den behöver.

F: Varför är texten som returneras identisk med det jag skickade? S: Det är avsiktligt. Vi känner inte igen och skriver inte om, vi linjerar bara tiden — texten kan alltså aldrig "rättas till en felstavning".

F: coverage är högt men det låter ändå lite förskjutet. S: Felet per tecken ligger oftast på några tiotals millisekunder; är hela låten förskjuten ett fast värde finns det troligen en tystnad i början av ljudet — klipp bort den och försök igen.

F: Varför fungerade separeringen nyss men nu står det "sångspåret är inte tillgängligt"? S: Separeringsresultat är kortlivade tillfälliga adresser (mätt: upphör efter ungefär en halvtimme). Då försöker ändpunkten separera igen automatiskt; misslyckas det ändå blir det full återbetalning. Så "separera nu, kalibrera senare" är inte tillförlitligt — gör båda i samma flöde.

F: Måste jag separera en plattformslåt själv först? S: Nej. Med vocal_separate: true kontrollerar vi om låten redan har ett sångspår; finns inget användbart ger vi fel och återbetalar i stället för att skicka vidare fullmixen.

F: Går det i batcher? S: En låt per begäran. För batcher, loopa; varje anrop debiteras normalt, så cacha resultaten lokalt.

F: Sparas resultatet? S: Den här ändpunkten sparar inget; spara returvärdet själv (rad- och teckentidsstämplar finns i svaret).