Documentation Index
Fetch the complete documentation index at: https://docs.lyrcs.ai/llms.txt
Use this file to discover all available pages before exploring further.
Endpoint
GET https://lyrcs.ai/api/v1/jobs/{job_id}
Job status values
| Status | Meaning |
|---|
processing | Transcription or alignment is still running |
complete | Results are ready |
failed | Processing failed — transcript could not be generated, or alignment timed out after 10 minutes |
Poll every 10 seconds with a 3-minute timeout. Jobs typically complete in 60–90 seconds depending on audio duration and pipeline mode.
Response shapes
Processing
{
"job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "processing",
"language": "Tamil",
"align_requested": true,
"created_at": "2024-01-01T00:00:00.000Z",
"completed_at": null
}
Complete — align=true (default)
{
"job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "complete",
"language": "Tamil",
"align_requested": true,
"created_at": "2024-01-01T00:00:00.000Z",
"completed_at": "2024-01-01T00:01:32.000Z",
"duration_seconds": 214,
"studio_url": "https://lyrcs.ai/studio/a1b2c3d4-...",
"results": {
"transcript": "நான் உன்னை நேசிக்கிறேன்\nதெரியாமல் போனேன்...",
"transliteration": "Naan unnai nesikirein\nTheriyaamal ponein...",
"translation": "I love you\nI didn't know...",
"cultural_notes": null,
"downloads": {
"lrc_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/original",
"lrc_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/transliterated",
"srt_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/srt/original",
"srt_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/srt/transliterated"
}
}
}
Complete — align=false
When align=false was passed at submission, downloads is omitted from the response.
{
"job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "complete",
"language": "Telugu",
"align_requested": false,
"created_at": "2024-01-01T00:00:00.000Z",
"completed_at": "2024-01-01T00:01:02.000Z",
"duration_seconds": 187,
"studio_url": "https://lyrcs.ai/studio/a1b2c3d4-...",
"results": {
"transcript": "...",
"transliteration": "...",
"translation": "...",
"cultural_notes": null
}
}
Failed
{
"job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "failed",
"language": "Tamil",
"align_requested": true,
"created_at": "2024-01-01T00:00:00.000Z",
"completed_at": null,
"error": "processing_failed"
}
Additional fields
Review fields
Present when review=true was passed at submission:
{
"review_required": true,
"review_url": "https://lyrcs.ai/review/a1b2c3d4-...?token=...",
"review_expires_at": "2024-01-02T00:00:00.000Z",
"review_approved_at": null
}
review_url is null until alignment completes and the token is generated. review_approved_at is null until the artist approves.
Audio URL field
Present when the job was submitted via audio_url mode:
{
"audio_url": "https://cdn.example.com/songs/song-123.mp3"
}
studio_url
A link to the lyrcs.ai Studio where the transcript can be edited and reviewed. Requires a lyrcs.ai user account to view. Not intended for end-users — this is an internal review tool for distributors.
Results fields
| Field | Type | Notes |
|---|
transcript | string | Original lyrics in the source script |
transliteration | string | Phonetic romanisation of the lyrics |
translation | string | English translation |
cultural_notes | string | null | Contextual notes on cultural references, idioms, or wordplay. May be null if none are detected. |
downloads | object | Present only when align_requested: true and job is complete |
Examples
curl https://lyrcs.ai/api/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Authorization: Bearer $LYRCS_API_KEY"