LogoAI Music API
ログイン

API エンドポイント

タイムスタンプ付き歌詞

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

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

namerequireddescription
nameAuthorizationrequiredyesdescriptionBearer token containing the user's API key. Format: "Bearer YOUR_API_KEY".
nameContent-Typerequiredyesdescriptionapplication/json

requestBody

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

commonParams

paramNameparamTyperequireddescriptionexample
paramNameaudio_idparamTypestringrequiredyesdescriptionThe audio asset ID obtained from /v2/feed or the callback payload. Identifies which song (of the pair) to align.examplefc490335-ad97-4444-ac64-0fb21c0d4308
paramNametask_idparamTypestringrequiredyesdescriptionGeneration task identifier (workId/data.task_id) returned by /v2/generate or /v2/extend.examplegen2b9bb36e6c0cc44567aa34fbcff3afa64bksv

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.

fieldparamTypedescriptionexample
fieldcodeparamTypenumberdescriptionApplication-level status indicator. 200 means the alignment job succeeded.example200
fieldmessageparamTypestringdescriptionHuman-readable status string accompanying the code.examplesuccess
fielddataparamTypeobjectdescriptionContainer holding lyric alignment metrics and waveform data for the requested audio.example

data fields

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

fieldparamTypedescriptionexample
fielddata.lyricAlignmentparamTypeobjectdescriptionAlignment payload mapping lyrics back to precise audio timings.example
fielddata.lyricAlignment.wordsparamTypeArray<LyricWord>descriptionOrdered list of lyric fragments (words, markers, or labels) annotated with timing metadata.example
fielddata.audioWaveformparamTypenumber[]descriptionNormalised amplitude samples that let you render lightweight waveform visualisations without re-analysing audio.example[0.00006,0,0.0339]
fielddata.alignmentScoreparamTypenumberdescriptionGlobal accuracy score (lower is better) derived from CER-style metrics.example0.175
fielddata.isStreamingparamTypebooleandescriptionFlags whether the audio was streamed live or delivered as a complete file, useful for adjusting UI states.examplefalse

LyricWord object

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

fieldparamTypedescriptionexample
fieldtextparamTypestringdescriptionOriginal lyric token or marker, e.g., a sung word or section label like [Verse].example[Verse]\nLola
fieldalignedparamTypebooleandescriptionTrue when the token was successfully matched to a time range in the audio.exampletrue
fieldstartTimeparamTypenumberdescriptionStart timestamp (seconds) where the lyric becomes audible.example0.55851
fieldendTimeparamTypenumberdescriptionEnd timestamp (seconds) marking when the lyric finishes.example0.87766
fieldconfidenceparamTypenumberdescriptionAlignment confidence score between 0–1. Higher means a more reliable match.example0.92

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

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;