Skip to main content

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

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.
Returns 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
}

​
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 script
  • words_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.