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

# POST /align

> Run word-level alignment against lyrics you already have — skips transcription entirely

## Endpoint

```
POST https://lyrcs.ai/api/v1/align
```

<Tip>
  **Ideal for distributors who already have lyrics in their catalog.** Use this endpoint when you have existing lyrics and only need word-level timestamps added. Skips transcription entirely, reducing both cost and latency.
</Tip>

Returns `202 Accepted` immediately — alignment runs asynchronously. The resulting job is identical to a `/transcribe` job with `word_align=true` and can be polled and downloaded the same way.

## Parameters

All parameters are passed as `application/json`.

### `audio_url` — required

An HTTPS URL pointing to the audio file. Must use `https://`. No size limit — the file is fetched server-side during processing.

### `language` — required

The source language of the lyrics. Must be the exact full name as returned by `GET /api/v1/languages`. Values are **case-sensitive**.

### `transcription` — required

The original script lyrics as a newline-separated string. Each line corresponds to one lyric line. Must match the language specified.

```
"ये दूरियाँ\nइन राहों में ये दूरियाँ\nसुन तो ज़रा..."
```

### `transliteration` — optional

Roman script (phonetic) transliteration of the lyrics, also newline-separated. When provided, `words_transliterated` is populated in the result. When omitted, only `words_original` is available.

```
"ye dooriyaan\nin raahon mein ye dooriyaan\nsun to zaraa..."
```

### `webhook_url` — optional

An HTTPS URL where the `job.complete` (or `job.failed`) event payload will be delivered on completion. Retry schedule: immediate, +1 min, +5 min, +30 min.

## Response — 202 Accepted

```json theme={null}
{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "language": "Hindi",
  "created_at": "2024-01-01T00:00:00.000Z",
  "word_align_requested": true
}
```

## Response — 403 Forbidden

```json theme={null}
{
  "error": "forbidden",
  "message": "This API key does not have access to the alignment endpoint",
  "code": "AUTH_002"
}
```

Returned when the API key has been provisioned for transcript-only access. Contact your account administrator if you need alignment enabled.

## Polling and downloads

Use `job_id` to poll `GET /api/v1/jobs/{job_id}` exactly as you would for a `/transcribe` job. When `status` is `"complete"`, `results.downloads` contains:

* `words_original` — per-word timestamps in the original script
* `words_transliterated` — per-word timestamps in Roman script (only when `transliteration` was provided)

LRC and SRT files are also generated and available at the standard `lrc_*` and `srt_*` download URLs.

See the [Jobs reference](/api-reference/jobs) for full polling examples and the [Download reference](/api-reference/download) for download endpoint details.

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://lyrcs.ai/api/v1/align \
    -H "Authorization: Bearer $LYRCS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "audio_url": "https://cdn.example.com/songs/song-123.mp3",
      "language": "Hindi",
      "transcription": "ये दूरियाँ\nइन राहों में ये दूरियाँ\nसुन तो ज़रा",
      "transliteration": "ye dooriyaan\nin raahon mein ye dooriyaan\nsun to zaraa",
      "webhook_url": "https://api.example.com/webhooks/lyrcs"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://lyrcs.ai/api/v1/align", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LYRCS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      audio_url: "https://cdn.example.com/songs/song-123.mp3",
      language: "Hindi",
      transcription: "ये दूरियाँ\nइन राहों में ये दूरियाँ\nसुन तो ज़रा",
      transliteration: "ye dooriyaan\nin raahon mein ye dooriyaan\nsun to zaraa",
      webhook_url: "https://api.example.com/webhooks/lyrcs",
    }),
  });

  const { job_id } = await response.json();
  console.log("Alignment queued:", job_id);
  ```

  ```python Python theme={null}
  import os, requests

  response = requests.post(
      "https://lyrcs.ai/api/v1/align",
      headers={"Authorization": f"Bearer {os.environ['LYRCS_API_KEY']}"},
      json={
          "audio_url": "https://cdn.example.com/songs/song-123.mp3",
          "language": "Hindi",
          "transcription": "ये दूरियाँ\nइन राहों में ये दूरियाँ\nसुन तो ज़रा",
          "transliteration": "ye dooriyaan\nin raahon mein ye dooriyaan\nsun to zaraa",
          "webhook_url": "https://api.example.com/webhooks/lyrcs",
      },
  )

  job_id = response.json()["job_id"]
  print("Alignment queued:", job_id)
  ```
</CodeGroup>

## Credits

`POST /align` deducts **1 credit** per job on completion, the same as `POST /transcribe`. The credit is charged when alignment finishes, not at submission time.