Timestamped Lyrics
Retrieve word-level timestamped lyrics for karaoke-style displays and precise music timing workflows.
Use the unified API in One gateway for all Suno routes.
Returns timing data directly when the audio is available.
Charged per timestamped lyrics request.
/api/v1/audio/music/timestamped-lyricsRetrieve Lyrics Timing
Get segment and word-level timing metadata for a generated audio clip.
Send the completed music task ID and audio clip ID to retrieve lyrics text, timing ranges, segment metadata, and waveform data.
- Use task_id from the original music task.
- Use audio_id from the completed Feed API response.
- Build karaoke, captions, or timeline UIs from lyricParams.
Body Parameters
The task ID that generated the music, usually returned by POST /api/v1/audio/music.
The specific audio clip ID from the Feed API response.
cURL Example
| 1 | curl -X POST "https://apiin.one/api/v1/audio/music/timestamped-lyrics" \ |
| 2 | -H "Authorization: Bearer aio_your_api_key_here" \ |
| 3 | -H "Content-Type: application/json" \ |
| 4 | -d '{ |
| 5 | "task_id": "gen123abc456def789ksv", |
| 6 | "audio_id": "song_abc123" |
| 7 | }' |
Timing Response
Synchronous response returning complete timing data.
| 1 | { |
| 2 | "code": 200, |
| 3 | "message": "success", |
| 4 | "data": { |
| 5 | "text": "[Verse 1]\nIt's a beautiful day...", |
| 6 | "lyricParams": [ |
| 7 | { |
| 8 | "text": "[Verse 1]\n", |
| 9 | "metadata": { |
| 10 | "style": "Verse 1" |
| 11 | }, |
| 12 | "type": "segment_break" |
| 13 | }, |
| 14 | { |
| 15 | "text": "It's a beautiful day", |
| 16 | "start": 11.23, |
| 17 | "end": 14.89, |
| 18 | "type": "lyric" |
| 19 | } |
| 20 | ], |
| 21 | "waveform": [ |
| 22 | 0.2, |
| 23 | 0.4, |
| 24 | 0.5 |
| 25 | ] |
| 26 | } |
| 27 | } |
Error Handling
API in One uses consistent authentication, credit, and validation errors across Suno endpoints.
Missing task_id or audio_id.
Invalid or missing API key.
Audio or lyrics not found.