Skip to main content
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:
Let the model transcribe lyrics from the audio.
{
  "type": "transcribe",
  "syncModel": "audioshake-transcription",
  "language": "en"
}

​
Sync models

Alignment models — use when you already have accurate lyrics (align):
  • audioshake-alignment
  • musicai-alignment
  • musicai-alignment-subword
Transcription models — use when the model should extract lyrics from the audio (transcribe):
  • audioshake-transcription
  • musicai-transcription
  • wav2vec2
  • whisper
See Sync model reference 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