Skip to main content

​
Endpoint

POST https://lyrcs.ai/api/v1/transcribe
Accepts multipart/form-data (for file uploads) or application/json (for URL-based jobs). Returns 202 Accepted immediately — processing is asynchronous.

​
Parameters

​
language — required

The source language of the audio. Must be the exact full name as returned by GET /api/v1/languages. Values are case-sensitive. 
"Tamil"       ✓
"Hindi"       ✓
"tamil"       ✗  → 400 validation_error
"HINDI"       ✗  → 400 validation_error

​
file — required if audio_url absent

Audio file, submitted as multipart/form-data. Accepted formats: mp3, wav, flac, m4a, aac, ogg, webm.
The Vercel serverless body limit is ~4.5 MB. For larger files — most production audio — use audio_url instead.

​
audio_url — required if file absent

An HTTPS URL pointing to the audio file. Must use https:// — HTTP URLs are rejected.
  • No size limit
  • URL must be publicly accessible at processing time (typically within 30s of submission)
  • One-time-use presigned URLs are supported

​
align — optional, default true

Controls whether time-alignment runs after transcription.
ValueOutputTime
true (default)Transcript + transliteration + translation + LRC + SRT + word-level JSON~90s
falseTranscript + transliteration + translation only~60s
When false, the downloads object is omitted from the job response and webhook payload.

​
word_align — optional, default true

Controls whether word-level timestamps are generated in addition to line-level LRC/SRT. Only takes effect when align=true.
ValueOutputNotes
true (default)Line-level LRC + SRT + per-word JSON timestamps4 Gemini calls
falseLine-level LRC + SRT only3 Gemini calls — marginally faster and cheaper
When true, words_original and words_transliterated are added to results.downloads on completion. When false, those keys are absent.

​
review — optional, default false

When true, the job fires job.awaiting_review instead of job.complete after alignment. Results are held until an artist approves via the review URL. Requires webhook_url to be useful.

​
webhook_url — optional

An HTTPS URL where event payloads will be delivered. Supported in JSON body only — not in multipart/form-data. Webhook events: job.complete, job.awaiting_review, job.degraded, job.failed. See the Webhooks guide for payload shapes and retry behaviour.

​
Response — 202 Accepted

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "language": "Tamil",
  "created_at": "2024-01-01T00:00:00.000Z",
  "review_required": false,
  "align_requested": true,
  "word_align_requested": true
}
Use job_id to poll GET /api/v1/jobs/{job_id} for status and results.

​
Examples

​
Basic file upload

curl -X POST https://lyrcs.ai/api/v1/transcribe \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -F "file=@song.mp3" \
  -F "language=Tamil"

curl -X POST https://lyrcs.ai/api/v1/transcribe \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://cdn.example.com/songs/song-123.mp3",
    "language": "Hindi",
    "webhook_url": "https://api.example.com/webhooks/lyrcs"
  }'

​
Transcript only — align=false

Use when you need metadata (lyrics text) but not time-synced files. Faster and sufficient for streaming store metadata delivery or liner notes. 
curl -X POST https://lyrcs.ai/api/v1/transcribe \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://cdn.example.com/songs/song-123.mp3",
    "language": "Telugu",
    "align": false
  }'

​
With artist review gate — review=true

Use when results must be approved by the artist before delivery. 
curl -X POST https://lyrcs.ai/api/v1/transcribe \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://cdn.example.com/songs/song-123.mp3",
    "language": "Punjabi",
    "review": true,
    "webhook_url": "https://api.example.com/webhooks/lyrcs"
  }'