> ## 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 /transcribe

> Submit an audio file for transcription, transliteration, translation, and alignment

## Endpoint

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

Accepts `multipart/form-data` (for file uploads) or `application/json` (for URL-based jobs). Returns `202 Accepted` immediately — processing is asynchronous.

## Parameters

### `language` — required

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

```
"Tamil"       ✓
"Hindi"       ✓
"tamil"       ✗  → 400 validation_error
"HINDI"       ✗  → 400 validation_error
```

### `file` — required if `audio_url` absent

Audio file, submitted as `multipart/form-data`. Accepted formats: **mp3, wav, flac, m4a, aac, ogg, webm**.

<Warning>
  The Vercel serverless body limit is \~4.5 MB. For larger files — most production audio — use `audio_url` instead.
</Warning>

### `audio_url` — required if `file` absent

An HTTPS URL pointing to the audio file. Must use `https://` — HTTP URLs are rejected.

* No size limit
* URL must be publicly accessible at processing time (typically within 30s of submission)
* One-time-use presigned URLs are supported

### `align` — optional, default `true`

Controls whether time-alignment runs after transcription.

| Value            | Output                                                                   | Time  |
| ---------------- | ------------------------------------------------------------------------ | ----- |
| `true` (default) | Transcript + transliteration + translation + LRC + SRT + word-level JSON | \~90s |
| `false`          | Transcript + transliteration + translation only                          | \~60s |

When `false`, the `downloads` object is **omitted** from the job response and webhook payload.

### `word_align` — optional, default `true`

Controls whether word-level timestamps are generated in addition to line-level LRC/SRT. Only takes effect when `align=true`.

| Value            | Output                                          | Notes                                          |
| ---------------- | ----------------------------------------------- | ---------------------------------------------- |
| `true` (default) | Line-level LRC + SRT + per-word JSON timestamps | 4 Gemini calls                                 |
| `false`          | Line-level LRC + SRT only                       | 3 Gemini calls — marginally faster and cheaper |

When `true`, `words_original` and `words_transliterated` are added to `results.downloads` on completion. When `false`, those keys are absent.

### `review` — optional, default `false`

When `true`, the job fires `job.awaiting_review` instead of `job.complete` after alignment. Results are held until an artist approves via the review URL. Requires `webhook_url` to be useful.

### `webhook_url` — optional

An HTTPS URL where event payloads will be delivered. Supported in JSON body only — not in `multipart/form-data`.

Webhook events: `job.complete`, `job.awaiting_review`, `job.degraded`, `job.failed`. See the [Webhooks guide](/guides/webhooks) for payload shapes and retry behaviour.

## Response — 202 Accepted

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

Use `job_id` to poll `GET /api/v1/jobs/{job_id}` for status and results.

## Examples

### Basic file upload

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://lyrcs.ai/api/v1/transcribe \
    -H "Authorization: Bearer $LYRCS_API_KEY" \
    -F "file=@song.mp3" \
    -F "language=Tamil"
  ```

  ```javascript Node.js theme={null}
  import { readFileSync } from "fs";

  const form = new FormData();
  form.append("file", new Blob([readFileSync("song.mp3")], { type: "audio/mpeg" }), "song.mp3");
  form.append("language", "Tamil");

  const response = await fetch("https://lyrcs.ai/api/v1/transcribe", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.LYRCS_API_KEY}` },
    body: form,
  });

  const { job_id } = await response.json();
  ```

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

  with open("song.mp3", "rb") as f:
      response = requests.post(
          "https://lyrcs.ai/api/v1/transcribe",
          headers={"Authorization": f"Bearer {os.environ['LYRCS_API_KEY']}"},
          files={"file": ("song.mp3", f, "audio/mpeg")},
          data={"language": "Tamil"},
      )

  job_id = response.json()["job_id"]
  ```
</CodeGroup>

### audio\_url mode (recommended for production)

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://lyrcs.ai/api/v1/transcribe \
    -H "Authorization: Bearer $LYRCS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "audio_url": "https://cdn.example.com/songs/song-123.mp3",
      "language": "Hindi",
      "webhook_url": "https://api.example.com/webhooks/lyrcs"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://lyrcs.ai/api/v1/transcribe", {
    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",
      webhook_url: "https://api.example.com/webhooks/lyrcs",
    }),
  });
  ```

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

  response = requests.post(
      "https://lyrcs.ai/api/v1/transcribe",
      headers={"Authorization": f"Bearer {os.environ['LYRCS_API_KEY']}"},
      json={
          "audio_url": "https://cdn.example.com/songs/song-123.mp3",
          "language": "Hindi",
          "webhook_url": "https://api.example.com/webhooks/lyrcs",
      },
  )
  ```
</CodeGroup>

### Transcript only — align=false

Use when you need metadata (lyrics text) but not time-synced files. Faster and sufficient for streaming store metadata delivery or liner notes.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://lyrcs.ai/api/v1/transcribe \
    -H "Authorization: Bearer $LYRCS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "audio_url": "https://cdn.example.com/songs/song-123.mp3",
      "language": "Telugu",
      "align": false
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://lyrcs.ai/api/v1/transcribe", {
    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: "Telugu",
      align: false,
    }),
  });
  ```

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

  response = requests.post(
      "https://lyrcs.ai/api/v1/transcribe",
      headers={"Authorization": f"Bearer {os.environ['LYRCS_API_KEY']}"},
      json={
          "audio_url": "https://cdn.example.com/songs/song-123.mp3",
          "language": "Telugu",
          "align": False,
      },
  )
  ```
</CodeGroup>

### With artist review gate — review=true

Use when results must be approved by the artist before delivery.

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://lyrcs.ai/api/v1/transcribe \
    -H "Authorization: Bearer $LYRCS_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "audio_url": "https://cdn.example.com/songs/song-123.mp3",
      "language": "Punjabi",
      "review": true,
      "webhook_url": "https://api.example.com/webhooks/lyrcs"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://lyrcs.ai/api/v1/transcribe", {
    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: "Punjabi",
      review: true,
      webhook_url: "https://api.example.com/webhooks/lyrcs",
    }),
  });
  ```

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

  response = requests.post(
      "https://lyrcs.ai/api/v1/transcribe",
      headers={"Authorization": f"Bearer {os.environ['LYRCS_API_KEY']}"},
      json={
          "audio_url": "https://cdn.example.com/songs/song-123.mp3",
          "language": "Punjabi",
          "review": True,
          "webhook_url": "https://api.example.com/webhooks/lyrcs",
      },
  )
  ```
</CodeGroup>