Download - lyrcs.ai

Six download endpoints are available for each completed job where align=true (the default). All require authentication.

LRC and SRT endpoints

Endpoint	Description
`GET /api/v1/jobs/{id}/download/lrc/original`	LRC file in the source language script
`GET /api/v1/jobs/{id}/download/lrc/transliterated`	LRC file with romanised (transliterated) lyrics
`GET /api/v1/jobs/{id}/download/srt/original`	SRT file in the source language script
`GET /api/v1/jobs/{id}/download/srt/transliterated`	SRT file with romanised lyrics

Word-level JSON endpoints

Endpoint	Description
`GET /api/v1/jobs/{id}/download/words/original`	Per-word timestamps in the source language script
`GET /api/v1/jobs/{id}/download/words/transliterated`	Per-word timestamps in romanised form

These endpoints are only available when the job was submitted with word_align=true (the default). They return a JSON array where each entry contains a single word and its start timestamp. Response — 200 OK:

[
  { "word": "நான்", "timestamp": "[00:12.34]" },
  { "word": "உன்னை", "timestamp": "[00:12.71]" },
  { "word": "நேசிக்கிறேன்", "timestamp": "[00:13.10]" }
]

Content-Type: application/json; charset=utf-8
Content-Disposition: attachment; filename="<original_filename>[_transliterated]_words.json"

Not ready yet — 202: If word-level alignment has not completed, the endpoint returns 202:

{ "status": "processing", "stage": "aligning" }

Only fetch word-level downloads once GET /api/v1/jobs/{id} returns status: "complete" and words_original appears in results.downloads. If the job was not submitted with word_align=true, word-level timings are never produced and the endpoint returns 409 rather than 202 — see Terminal responses below.

Response — 200 OK

Returns a plain-text file with:

Content-Type: text/plain; charset=utf-8
Content-Disposition: attachment; filename="<original_filename>[_transliterated].<ext>"

Not ready yet — 202

If the job exists but alignment has not completed, the endpoint returns 202 instead of 404:

{ "status": "processing", "stage": "aligning" }

202 always means keep waiting — the output is still coming. Poll GET /api/v1/jobs/{id} and fetch downloads once status is "complete".

Terminal responses

A 409 means stop polling — this file is never going to exist. There are two reasons, distinguished by the code: The job failed (JOB_001):

{
  "error": "job_failed",
  "message": "Alignment did not complete within 300s of dispatch",
  "code": "JOB_001",
  "status": "failed",
  "stage": "alignment"
}

The output was never requested (JOB_002) — the job was submitted with align=false, or word-level timings were requested on a job with word_align=false:

{
  "error": "alignment_not_requested",
  "message": "This job was submitted with align=false, so no LRC was generated.",
  "code": "JOB_002"
}

These previously returned 202 { "status": "processing" } indefinitely, which gave a caller no way to tell “still working” from “never coming”. Treat 202 as retry and 409 as terminal.

Download URLs are returned directly in results.downloads on the job response and in the job.complete webhook payload. You do not need to construct them manually.

Examples

# Original script LRC
curl https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/original \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -o song.lrc

# Transliterated LRC
curl https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/lrc/transliterated \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -o song_transliterated.lrc

# Original script SRT
curl https://lyrcs.ai/api/v1/jobs/a1b2c3d4-.../download/srt/original \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -o song.srt

async function downloadLrc(jobId, type, apiKey) {
  // type: "original" | "transliterated"
  const res = await fetch(
    `https://lyrcs.ai/api/v1/jobs/${jobId}/download/lrc/${type}`,
    { headers: { Authorization: `Bearer ${apiKey}` } }
  );

  if (res.status === 202) {
    throw new Error("LRC not ready yet — job still processing");
  }
  if (!res.ok) throw new Error(`HTTP ${res.status}`);

  return res.text(); // standard LRC content
}

const lrcOriginal = await downloadLrc("a1b2c3d4-...", "original", process.env.LYRCS_API_KEY);
const lrcTranslit = await downloadLrc("a1b2c3d4-...", "transliterated", process.env.LYRCS_API_KEY);

import os, requests

def download_lrc(job_id, lrc_type, api_key):
    # lrc_type: "original" | "transliterated"
    r = requests.get(
        f"https://lyrcs.ai/api/v1/jobs/{job_id}/download/lrc/{lrc_type}",
        headers={"Authorization": f"Bearer {api_key}"},
    )
    if r.status_code == 202:
        raise RuntimeError("LRC not ready yet — job still processing")
    r.raise_for_status()
    return r.text

lrc_original = download_lrc("a1b2c3d4-...", "original", os.environ["LYRCS_API_KEY"])
lrc_translit = download_lrc("a1b2c3d4-...", "transliterated", os.environ["LYRCS_API_KEY"])

Download from webhook payload

If you’re using webhooks, the download URLs arrive in the job.complete payload:

{
  "event": "job.complete",
  "job_id": "a1b2c3d4-...",
  "results": {
    "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"
    }
  }
}

All four URLs require your API key in the Authorization header to fetch. See LRC & SRT Formats for a description of the file formats and when to use each.

​LRC and SRT endpoints

​Word-level JSON endpoints

​Response — 200 OK

​Not ready yet — 202

​Terminal responses

​Examples

​Download from webhook payload

LRC and SRT endpoints

Word-level JSON endpoints

Response — 200 OK

Not ready yet — 202

Terminal responses

Examples

Download from webhook payload