POST /transcribe - lyrcs.ai

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.

The Vercel serverless body limit is ~4.5 MB. For larger files — most production audio — use audio_url instead.

`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 for payload shapes and retry behaviour.

`external_id` — optional

An arbitrary string (max 255 characters) that you can use to map the job back to a track in your own system. Supported in JSON body only — not in multipart/form-data. When provided, external_id is echoed back in:

The 202 submission response
GET /api/v1/jobs/{job_id}
The job.complete webhook payload

When omitted, the field is present but null in all responses.

Response — 202 Accepted

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "external_id": "TRACK_12345",
  "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

curl -X POST https://lyrcs.ai/api/v1/transcribe \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -F "file=@song.mp3" \
  -F "language=Tamil"

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();

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"]

audio_url mode (recommended for production)

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"
  }'

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",
  }),
});

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",
    },
)

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.

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
  }'

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,
  }),
});

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,
    },
)

With external_id for track mapping

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",
    "external_id": "CATALOG_76007488",
    "align": false
  }'

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",
    external_id: "CATALOG_76007488",
    align: false,
  }),
});

const { job_id, external_id } = await response.json();
// external_id === "CATALOG_76007488"

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",
        "external_id": "CATALOG_76007488",
        "align": False,
    },
)

data = response.json()
# data["external_id"] == "CATALOG_76007488"

With artist review gate — review=true

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

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"
  }'

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",
  }),
});

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",
    },
)

​Endpoint

​Parameters

​language — required

​file — required if audio_url absent

​audio_url — required if file absent

​align — optional, default true

​word_align — optional, default true

​review — optional, default false

​webhook_url — optional

​external_id — optional

​Response — 202 Accepted

​Examples

​Basic file upload

​audio_url mode (recommended for production)

​Transcript only — align=false

​With external_id for track mapping

​With artist review gate — review=true

Endpoint

Parameters

`language` — required

`file` — required if `audio_url` absent

`audio_url` — required if `file` absent

`align` — optional, default `true`

`word_align` — optional, default `true`

`review` — optional, default `false`

`webhook_url` — optional

`external_id` — optional

Response — 202 Accepted

Examples

Basic file upload

audio_url mode (recommended for production)

Transcript only — align=false

With external_id for track mapping

With artist review gate — review=true