API Endpoints

Timestamped Lyrics

POST/v2/timestamped-lyrics

Timestamped Lyrics API

Retrieve word-level lyric timestamps, waveform data, and alignment insights for a generated track.

POSThttps://udioapi.pro/api/v2/timestamped-lyrics

tips

Call this endpoint after generation completes to get timed lyrics.

Provide audio_id and task_id.

requestHeaders

namerequireddescription
AuthorizationyesBearer token for authentication
Content-Typeyesapplication/json

requestBody

Provide both identifiers for alignment lookup

commonParams

paramNameparamTyperequireddescriptionexample
audio_idstringyesAudio asset ID from feed or callbackfc490335-ad97-4444-ac64-0fb21c0d4308
task_idstringyesGeneration task identifier returned by generate or extendgen2b9bb36e6c0cc44567aa34fbcff3afa64bksv

responses

json
{
  "code": 200,
  "message": "success",
  "data": {
    "lyricAlignment": {
      "words": [
        {
          "text": "[Verse]\nLola ",
          "aligned": true,
          "startTime": 0.55851,
          "endTime": 0.87766,
          "confidence": 0
        },
        {
          "text": "Chouch, ",
          "aligned": true,
          "startTime": 0.91755,
          "endTime": 1.91489,
          "confidence": 0
        }
      ]
    },
    "audioWaveform": [
      0.00006,
      0,
      0.0339
    ],
    "alignmentScore": 0.175,
    "isStreaming": false
  }
}
json
{
  "code": 401,
  "message": "Missing or invalid Authorization header. Use 'Bearer YOUR_API_KEY'",
  "data": null
}
json
{
  "code": 400,
  "message": "Task ID and Audio ID are required, please provide both task_id and audio_id in the request body",
  "data": null
}
json
{
  "code": 400,
  "message": "Invalid task id",
  "data": null
}
json
{
  "code": 400,
  "message": "Your request is being processed. Please wait until it completes.",
  "status": "IN_PROGRESS",
  "data": null
}
json
{
  "code": 400,
  "message": "Audio ID does not match the Task ID, please check and try again",
  "data": null
}
json
{
  "code": 500,
  "message": "Internal Server Error, please try again later",
  "data": null
}

codeExamples

curl
curl -X POST "https://udioapi.pro/api/v2/timestamped-lyrics" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_id": "fc490335-ad97-4e08-ac64-0fb91c0d4308",
    "task_id": "gen2b9bb36e6c0cc47969aa34fbcff3afa64bksv"
  }'
javascript
const response = await $fetch("https://udioapi.pro/api/v2/timestamped-lyrics", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: {
    audio_id: "fc490335-ad97-4e08-ac64-0fb91c0d4308",
    task_id: "gen2b9bb36e6c0cc47969aa34fbcff3afa64bksv",
  },
});

const { data } = response;
const lyricWords = data.lyricAlignment.words;
const waveform = data.audioWaveform;