Skip to main content

​
Prerequisites

You’ll need an API key. See Authentication for how to request one. Set your key as an environment variable: 
export LYRCS_API_KEY="lyrcs_sk_live_..."

​
Step 1: Submit a transcription job

Send an audio URL and the source language. The API returns a job_id immediately — processing happens asynchronously. 
curl -X POST https://lyrcs.ai/api/v1/transcribe \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/song.mp3",
    "language": "Tamil"
  }'
Response: 
{
  "job_id": "a1b2c3d4-...",
  "status": "queued",
  "language": "Tamil",
  "created_at": "2024-01-01T00:00:00.000Z",
  "review_required": false,
  "align_requested": true,
  "word_align_requested": true
}
Use GET /api/v1/languages to see the exact accepted language name strings. Values are case-sensitive — "Tamil" works, "tamil" does not.

​
Step 2: Poll for completion

Poll GET /api/v1/jobs/{job_id} until status is "complete" or "failed". Jobs typically complete within 60–90 seconds. 
curl https://lyrcs.ai/api/v1/jobs/a1b2c3d4-... \
  -H "Authorization: Bearer $LYRCS_API_KEY"
Response when complete: 
{
  "job_id": "a1b2c3d4-...",
  "status": "complete",
  "language": "Tamil",
  "align_requested": true,
  "word_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": "...",
    "transliteration": "...",
    "translation": "...",
    "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",
      "words_original": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/words/original",
      "words_transliterated": "https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/words/transliterated"
    }
  }
}

​
Step 3: Download lyric files

Use any of the download URLs from results.downloads. Authentication is required. In addition to LRC and SRT, words_original and words_transliterated contain per-word timestamps as a JSON array — useful for word-by-word karaoke highlight. 
curl https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/original \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -o song.lrc
The response is a plain-text .lrc file with Content-Disposition: attachment.

​
What’s next

Three API Modes

When to use align=false, review=true, or the default pipeline.

Webhooks

Receive events instead of polling. Covers all 5 event types and signature verification.

Batch Processing

Submit up to 20 jobs at once with a single webhook on completion.

Error Reference

All error codes, HTTP statuses, and rate limit headers.