GET /jobs/[id] - lyrcs.ai

Endpoint

GET https://lyrcs.ai/api/v1/jobs/{job_id}

Returns the current status of a job and, once complete, the full results including transcript, transliteration, translation, and download URLs for LRC/SRT files.

Job status values

Status	Terminal?	Meaning
`processing`	No	Still running. Keep polling.
`complete`	Yes	Results are ready
`failed`	Yes	The pipeline recorded a failure. See the `error` object for which stage and why.

complete and failed are both terminal — a job never leaves either state, and never moves from failed back to complete. Once you see one of them you can stop polling. failed is only ever returned when the pipeline actually recorded a failure. It is never inferred from how long a job has been running, so a slow job is processing, not failed.

Stage

Alongside status, every response carries a finer-grained stage so you can watch a job advance without inferring progress from elapsed time.

Stage	Meaning
`transcribing`	Audio is being transcribed
`aligning`	Transcript is ready; timestamps are being generated
`done`	Everything requested has been produced
`failed`	See the `error` object

A job submitted with align=false goes straight from transcribing to done.

How long jobs take

Measured end to end on production traffic, a 3-minute track takes roughly 90–130 seconds of processing — about 0.4–0.8× the audio duration. Longer tracks and batches under load take longer.

Do not set a client-side timeout of a few minutes and treat expiry as failure. A job can legitimately stay in processing for up to 15 minutes — the pipeline itself allows 10 minutes for transcription and a further 5 for alignment before it gives up and records a failure.If a job genuinely fails or stalls, the API tells you so by returning failed. You do not need your own timeout to detect it, and adding one will make healthy jobs look broken.

Prefer webhooks over polling. Webhooks only fire on terminal states, so there is no in-flight ambiguity to interpret. If you do poll, every 10–15 seconds is plenty.

Response shapes

Processing

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CATALOG_76007488",
  "status": "processing",
  "stage": "aligning",
  "language": "Tamil",
  "align_requested": true,
  "word_align_requested": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "transcript_completed_at": "2024-01-01T00:00:38.000Z",
  "completed_at": null,
  "second_opinion": null,
  "alignment": null
}

transcript_completed_at is stamped when the transcript is ready, which is before alignment finishes. completed_at means the whole job is done. Use status rather than either timestamp to decide whether a job has finished.

Complete — align=true, word_align=true (default)

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CATALOG_76007488",
  "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": "நான் உன்னை நேசிக்கிறேன்\nதெரியாமல் போனேன்...",
    "transliteration": "Naan unnai nesikirein\nTheriyaamal ponein...",
    "translation": "I love you\nI didn't know...",
    "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"
    }
  },
  "second_opinion": null,
  "alignment": {
    "method": "forced",
    "coverage": 0.998,
    "line_flags": []
  }
}

words_original and words_transliterated are only present when word_align_requested: true and alignment is complete. Jobs submitted with word_align=false include only lrc_* and srt_* in downloads.

Complete — align=false

When align=false was passed at submission, downloads is omitted from the response.

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CATALOG_76007488",
  "status": "complete",
  "language": "Telugu",
  "align_requested": false,
  "word_align_requested": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "completed_at": "2024-01-01T00:01:02.000Z",
  "duration_seconds": 187,
  "studio_url": "https://lyrcs.ai/studio/a1b2c3d4-...",
  "results": {
    "transcript": "...",
    "transliteration": "...",
    "translation": "...",
    "cultural_notes": null
  }
}

Failed

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "CATALOG_76007488",
  "status": "failed",
  "stage": "failed",
  "language": "Tamil",
  "align_requested": true,
  "word_align_requested": true,
  "created_at": "2024-01-01T00:00:00.000Z",
  "transcript_completed_at": null,
  "completed_at": null,
  "error": {
    "stage": "transcription",
    "message": "Transcript did not appear within 600s of job creation",
    "failed_at": "2024-01-01T00:10:04.000Z"
  }
}

error.stage is the pipeline stage that failed — transcription or alignment. A job that failed at alignment still has a usable transcript in results; one that failed at transcription has nothing.

Additional fields

Review fields

Present when review=true was passed at submission:

{
  "review_required": true,
  "review_url": "https://lyrcs.ai/review/a1b2c3d4-...?token=...",
  "review_expires_at": "2024-01-02T00:00:00.000Z",
  "review_approved_at": null
}

review_url is null until alignment completes and the token is generated. review_approved_at is null until the artist approves.

second_opinion and alignment

Present on every response. Both are null when the corresponding check did not run — see Quality Signals for the full field reference.

{
  "second_opinion": {
    "total_lines": 59,
    "agreed_lines": 47,
    "match_ratio": 0.79,
    "suggestions": [],
    "hidden_count": 0
  },
  "alignment": {
    "method": "forced",
    "coverage": 0.998,
    "line_flags": []
  }
}

null means the check did not run. An empty suggestions array means it ran and agreed with every line — the opposite signal. Do not collapse the two into a single falsy test.

second_opinion is available as soon as the transcript is, so it is readable while a job is still aligning. alignment is null until alignment completes, and on jobs submitted with align=false.

external_id

Present on all jobs. Contains the value passed at submission, or null if not provided.

{
  "external_id": "CATALOG_76007488"
}

Use this to map a job back to a track in your own system without maintaining a separate job_id → track lookup.

Audio URL field

Present when the job was submitted via audio_url mode:

{
  "audio_url": "https://cdn.example.com/songs/song-123.mp3"
}

studio_url

A link to the lyrcs.ai Studio where the transcript can be edited and reviewed. Requires a lyrcs.ai user account to view. Not intended for end-users — this is an internal review tool for distributors.

Results fields

Field	Type	Notes
`transcript`	string	Original lyrics in the source script
`transliteration`	string	Phonetic romanisation of the lyrics
`translation`	string	English translation
`cultural_notes`	string \| null	Contextual notes on cultural references, idioms, or wordplay. May be null if none are detected.
`downloads`	object	Present only when `align_requested: true` and job is complete

Top-level quality fields

Field	Type	Notes
`second_opinion`	object \| null	An independent listener’s read of the transcript. `null` means not checked. See Quality Signals.
`alignment`	object \| null	How the timings were produced, and which lines look suspect. `null` until alignment completes.

Examples

curl https://lyrcs.ai/api/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $LYRCS_API_KEY"

async function waitForJob(jobId, apiKey, { intervalMs = 10000, timeoutMs = 180000 } = {}) {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(`https://lyrcs.ai/api/v1/jobs/${jobId}`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });

    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const job = await res.json();

    if (job.status === "complete") return job;
    if (job.status === "failed") throw new Error(`Job failed: ${jobId}`);

    await new Promise((r) => setTimeout(r, intervalMs));
  }

  throw new Error("Job timed out");
}

const job = await waitForJob("a1b2c3d4-...", process.env.LYRCS_API_KEY);
console.log("Transcript:", job.results.transcript);
console.log("LRC URL:", job.results.downloads?.lrc_original);

import os, time, requests

def wait_for_job(job_id, api_key, interval=10, timeout=180):
    headers = {"Authorization": f"Bearer {api_key}"}
    deadline = time.time() + timeout

    while time.time() < deadline:
        r = requests.get(
            f"https://lyrcs.ai/api/v1/jobs/{job_id}",
            headers=headers,
        )
        r.raise_for_status()
        job = r.json()

        if job["status"] == "complete":
            return job
        if job["status"] == "failed":
            raise RuntimeError(f"Job failed: {job_id}")

        time.sleep(interval)

    raise TimeoutError("Job timed out")

job = wait_for_job("a1b2c3d4-...", os.environ["LYRCS_API_KEY"])
print("Transcript:", job["results"]["transcript"])
print("LRC URL:", job["results"].get("downloads", {}).get("lrc_original"))

​Endpoint

​Job status values

​Stage

​How long jobs take

​Response shapes

​Processing

​Complete — align=true, word_align=true (default)

​Complete — align=false

​Failed

​Additional fields

​Review fields

​second_opinion and alignment

​external_id

​Audio URL field

​studio_url

​Results fields

​Top-level quality fields

​Examples

Endpoint

Job status values

Stage

How long jobs take

Response shapes

Processing

Complete — align=true, word_align=true (default)

Complete — align=false

Failed

Additional fields

Review fields

second_opinion and alignment

external_id

Audio URL field

studio_url

Results fields

Top-level quality fields

Examples