Lyrics sync

Lyrics sync aligns lyric text to the audio so words highlight at the right moment. Youka runs sync automatically when you create a project. Use this endpoint to re-run sync with a different model, updated lyrics, or a different language.

When to use

Re-sync when…

Timings are off, you edited the lyrics, you changed sync models, or you corrected the language.

Skip this endpoint when…

You’re creating a new project — pass lyricsSource to POST /projects instead of running sync twice.

Endpoint

POST /projects/{projectId}/tasks/lyrics-sync

Returns a taskId you can poll at GET /tasks/{taskId}. The original project state is untouched until the new task finishes.

Request

curl -X POST https://api.youka.io/api/v1/projects/prj_abc/tasks/lyrics-sync \
  -H "Authorization: Bearer yk_..." \
  -H "Idempotency-Key: resync-prj_abc-v2" \
  -H "Content-Type: application/json" \
  -d '{
    "lyricsSource": {
      "type": "align",
      "lyrics": "First line\nSecond line\n...",
      "syncModel": "audioshake-alignment",
      "language": "en"
    }
  }'

Lyrics source

Pass one of two source types via lyricsSource:

transcribe
align

Let the model transcribe lyrics from the audio.

{
  "type": "transcribe",
  "syncModel": "audioshake-transcription",
  "language": "en"
}

You pass exact lyrics. The model aligns them to the audio.

{
  "type": "align",
  "lyrics": "First line\nSecond line",
  "syncModel": "audioshake-alignment",
  "language": "en"
}

Sync models

Alignment models — use when you already have accurate lyrics (align):

audioshake-alignment
musicai-alignment
musicai-alignment-subword
wav2vec2

Transcription models — use when the model should extract lyrics from the audio (transcribe):

audioshake-transcription
elevenlabs-transcription
musicai-transcription
whisper

See Choose a lyrics sync model for guidance.

Polling

# Poll the task
curl https://api.youka.io/api/v1/tasks/tsk_abc \
  -H "Authorization: Bearer yk_..."

# Once the task is in a terminal state, re-read the project
curl https://api.youka.io/api/v1/projects/prj_abc \
  -H "Authorization: Bearer yk_..."

The updated project.lyrics contains the new word-level timings.

Pair every request with an idempotency key so retries don’t queue duplicate sync jobs.

What’s next

Stems — re-run stem separation before re-syncing
Async jobs — polling pattern
SDK lyrics sync — the same endpoint in TypeScript
Choose a lyrics sync model — pick the right model

Guides

Resources

API Reference

When to use

Re-sync when…

Skip this endpoint when…

Endpoint

Request

Lyrics source

Sync models

Polling

What’s next

​When to use

Re-sync when…

Skip this endpoint when…

​Endpoint

​Request

​Lyrics source

​Sync models

​Polling

​What’s next

When to use

Endpoint

Request

Lyrics source

Sync models

Polling

What’s next