> ## 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.

# Download

> Download LRC, SRT, and word-level JSON lyric files for a completed job

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:**

```json theme={null}
[
  { "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`:

```json theme={null}
{ "status": "processing" }
```

Only fetch word-level downloads once `GET /api/v1/jobs/{id}` returns `status: "complete"` and `words_original` appears in `results.downloads`.

## 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`:

```json theme={null}
{ "status": "processing" }
```

Poll `GET /api/v1/jobs/{id}` and only fetch downloads once `status` is `"complete"`.

## Not available for align=false jobs

If the job was submitted with `align=false`, no LRC or SRT files are generated. Calling the download endpoints will return `202 { "status": "processing" }` indefinitely since alignment never runs.

<Note>
  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.
</Note>

## Examples

<CodeGroup>
  ```bash curl theme={null}
  # 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
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

## Download from webhook payload

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

```json theme={null}
{
  "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](/guides/lrc-srt-formats) for a description of the file formats and when to use each.