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.

The review flow adds an artist approval gate between transcription and delivery. Results are held until an artist or rights holder confirms the lyrics are correct.

​
End-to-end flow

1

Distributor submits job with review=true

POST /api/v1/transcribe
{
  "audio_url": "https://cdn.example.com/song.mp3",
  "language": "Punjabi",
  "review": true,
  "webhook_url": "https://api.example.com/webhooks/lyrcs"
}
Returns 202 { "job_id": "...", "status": "queued", "review_required": true }.
2

Transcription and alignment run (~90 seconds)

lyrcs.ai transcribes the audio, generates transliteration and translation, then time-aligns the lyrics. No action needed from the distributor during this phase.
3

job.awaiting_review webhook fires

{
  "event": "job.awaiting_review",
  "job_id": "a1b2c3d4-...",
  "language": "Punjabi",
  "review_url": "https://lyrcs.ai/review/a1b2c3d4-...?token=abc123",
  "expires_at": "2024-01-02T00:00:00.000Z",
  "studio_url": "https://lyrcs.ai/studio/a1b2c3d4-..."
}
The distributor receives this at their webhook_url.
4

Distributor routes review_url to artist

Extract review_url and forward it to the artist — by email, SMS, or your own platform’s notification system. The artist does not need a lyrcs.ai account.
5

Artist reviews and approves

The artist visits the review_url and sees the full transcript, transliteration, and translation in the lyrcs.ai Studio. They can read through the lyrics and, if satisfied, click Approve.
6

job.complete fires with full results

{
  "event": "job.complete",
  "job_id": "a1b2c3d4-...",
  "language": "Punjabi",
  "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"
    }
  }
}
The distributor can now download and deliver the lyric files.

​
Polling for review status

If you’re polling rather than using webhooks, the GET /api/v1/jobs/{id} response includes review fields: 
{
  "job_id": "a1b2c3d4-...",
  "status": "complete",
  "review_required": true,
  "review_url": "https://lyrcs.ai/review/a1b2c3d4-...?token=abc123",
  "review_expires_at": "2024-01-02T00:00:00.000Z",
  "review_approved_at": "2024-01-01T14:22:00.000Z"
}
review_approved_at is null until approval. Once set, the job is approved and results are available.

​
Known limitations

review_url is null until alignment completes The review URL and token are only generated after alignment finishes (~90s). If you poll GET /jobs/{id} immediately after submission, review_url will be null. Wait for the job.awaiting_review webhook or poll until review_url is non-null. Single-attempt webhook delivery after approval The job.complete webhook fired after artist approval does not retry on failure — unlike the standard pipeline which retries at +1 min, +5 min, +30 min. Ensure your webhook endpoint is reliable. If you miss this delivery, poll GET /jobs/{id} — the review_approved_at field will be set and results will be available. Token expiry Review tokens expire. If the artist doesn’t approve before expires_at, contact api@lyrcs.ai to issue a new token.

​
Review in batch jobs

Batch jobs support review=true per job: 
{
  "webhook_url": "https://api.example.com/webhooks/lyrcs",
  "jobs": [
    { "audio_url": "https://cdn.example.com/song.mp3", "language": "Punjabi", "review": true }
  ]
}
Each job’s review_url appears in GET /api/v1/batch/{id} responses once alignment completes. The batch.complete webhook fires when all jobs are done — note that review=true batch jobs are considered complete (for batch-counting purposes) as soon as alignment finishes, not after artist approval. This means batch.complete may fire before all artists have approved; individual job.complete webhooks fire per approval.