Endpoint
POST https://lyrcs.ai/api/v1/align
Ideal for distributors who already have lyrics in their catalog. Use this endpoint when you have existing lyrics and only need word-level timestamps added. Skips transcription entirely, reducing both cost and latency.
202 Accepted immediately — alignment runs asynchronously. The resulting job is identical to a /transcribe job with word_align=true and can be polled and downloaded the same way.
Parameters
All parameters are passed as application/json.
audio_url — required
An HTTPS URL pointing to the audio file. Must use https://. No size limit — the file is fetched server-side during processing.
language — required
The source language of the lyrics. Must be the exact full name as returned by GET /api/v1/languages. Values are case-sensitive.
transcription — required
The original script lyrics as a newline-separated string. Each line corresponds to one lyric line. Must match the language specified.
"ये दूरियाँ\nइन राहों में ये दूरियाँ\nसुन तो ज़रा..."
transliteration — optional
Roman script (phonetic) transliteration of the lyrics, also newline-separated. When provided, words_transliterated is populated in the result. When omitted, only words_original is available.
"ye dooriyaan\nin raahon mein ye dooriyaan\nsun to zaraa..."
webhook_url — optional
An HTTPS URL where the job.complete (or job.failed) event payload will be delivered on completion. Retry schedule: immediate, +1 min, +5 min, +30 min.
Response — 202 Accepted
{
"job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "queued",
"language": "Hindi",
"created_at": "2024-01-01T00:00:00.000Z",
"word_align_requested": true
}
Response — 403 Forbidden
{
"error": "forbidden",
"message": "This API key does not have access to the alignment endpoint",
"code": "AUTH_002"
}
Polling and downloads
Use job_id to poll GET /api/v1/jobs/{job_id} exactly as you would for a /transcribe job. When status is "complete", results.downloads contains:
words_original — per-word timestamps in the original scriptwords_transliterated — per-word timestamps in Roman script (only when transliteration was provided)
LRC and SRT files are also generated and available at the standard lrc_* and srt_* download URLs.
See the Jobs reference for full polling examples and the Download reference for download endpoint details.
Example
curl -X POST https://lyrcs.ai/api/v1/align \
-H "Authorization: Bearer $LYRCS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://cdn.example.com/songs/song-123.mp3",
"language": "Hindi",
"transcription": "ये दूरियाँ\nइन राहों में ये दूरियाँ\nसुन तो ज़रा",
"transliteration": "ye dooriyaan\nin raahon mein ye dooriyaan\nsun to zaraa",
"webhook_url": "https://api.example.com/webhooks/lyrcs"
}'
Credits
POST /align deducts 1 credit per job on completion, the same as POST /transcribe. The credit is charged when alignment finishes, not at submission time.