Credit Cost

Every timestamped lyrics request consumes 2 credits. Factor this into your polling cadence and cache strategy so your UX stays responsive without overspending.

POST /v2/timestamped-lyrics

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 once a generation task completes so you can pair finished audio with perfectly timed lyrics in your player UI.

Key Identifiers

audio_id: Returned by the /v2/feed polling API or the webhook callback. Each generation typically yields two audio assets—pass the specific id you want timing data for.
task_id: The generation request identifier (a.k.a workId) returned by /v2/generate or /v2/extend. It anchors the lyric alignment job.

Tip: cache the timing payload alongside your audio file so subsequent playbacks feel instant.

requestHeaders

name	required	description
Authorization	Yes	Bearer token containing the user's API key. Format: "Bearer YOUR_API_KEY".
Content-Type	Yes	application/json

Request Body

Provide both identifiers so the service can locate the precise audio asset and its generation context.

Common Parameters

Parameter	Type	Required	Description	Example
audio_id	string	Yes	The audio asset ID obtained from /v2/feed or the callback payload. Identifies which song (of the pair) to align.	fc490335-ad97-4444-ac64-0fb21c0d4308
task_id	string	Yes	Generation task identifier (workId/data.task_id) returned by /v2/generate or /v2/extend.	gen2b9bb36e6c0cc44567aa34fbcff3afa64bksv

Response payload

Use these tables to inspect the structure returned after a successful or failed timestamped lyrics request.

Top-level envelope

Standard wrapper letting you catch transport-level issues while keeping the payload predictable.

Field	Type	Description	Example
code	number	Application-level status indicator. 200 means the alignment job succeeded.	200
message	string	Human-readable status string accompanying the code.	success
data	object	Container holding lyric alignment metrics and waveform data for the requested audio.

data fields

Use these fields to build lyric karaoke views, waveform scrubbing, or downstream analytics.

Field	Type	Description	Example
data.lyricAlignment	object	Alignment payload mapping lyrics back to precise audio timings.
data.lyricAlignment.words	Array<LyricWord>	Ordered list of lyric fragments (words, markers, or labels) annotated with timing metadata.
data.audioWaveform	number[]	Normalised amplitude samples that let you render lightweight waveform visualisations without re-analysing audio.	[0.00006,0,0.0339]
data.alignmentScore	number	Global accuracy score (lower is better) derived from CER-style metrics.	0.175
data.isStreaming	boolean	Flags whether the audio was streamed live or delivered as a complete file, useful for adjusting UI states.	false

LyricWord object

Each entry in data.lyricAlignment.words tracks a single token or segment.

Field	Type	Description	Example
text	string	Original lyric token or marker, e.g., a sung word or section label like [Verse].	[Verse]\nLola
aligned	boolean	True when the token was successfully matched to a time range in the audio.	true
startTime	number	Start timestamp (seconds) where the lyric becomes audible.	0.55851
endTime	number	End timestamp (seconds) marking when the lyric finishes.	0.87766
confidence	number	Alignment confidence score between 0–1. Higher means a more reliable match.	0.92

When aligned is false, you can choose to grey out the lyric or skip highlighting to keep playback feeling polished.

responses

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

codeExamples

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