Skip to main content

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 /api/v1/batch

Submit a batch of jobs. All jobs are processed concurrently. A single batch.complete webhook fires when all jobs are done.

​
Endpoint

POST https://lyrcs.ai/api/v1/batch
JSON only — file upload is not supported. Every job must use audio_url.

​
Body — two accepted shapes

Shape A: plain array 
[
  { "audio_url": "https://cdn.example.com/song-1.mp3", "language": "Hindi" },
  { "audio_url": "https://cdn.example.com/song-2.mp3", "language": "Tamil" },
  { "audio_url": "https://cdn.example.com/song-3.mp3", "language": "Telugu", "align": false }
]
Shape B: object with webhook 
{
  "webhook_url": "https://api.example.com/webhooks/lyrcs",
  "jobs": [
    { "audio_url": "https://cdn.example.com/song-1.mp3", "language": "Hindi" },
    { "audio_url": "https://cdn.example.com/song-2.mp3", "language": "Tamil" }
  ]
}

​
Per-job fields

FieldTypeRequiredDefault
audio_urlstringYes—
languagestringYes—
alignbooleanNotrue
reviewbooleanNofalse

​
Limits

  • Minimum 1 job, maximum 20 jobs per request
  • Rate limit check is pre-flight: if submitting N jobs would push any window over the limit, the entire batch is rejected with 429 before any jobs are created. See rate limit headers.

​
Response — 202 Accepted

{
  "batch_id": "b1a2t3c4-...",
  "job_count": 5,
  "status": "queued",
  "message": "Batch queued. Use GET /api/v1/batch/{batch_id} to poll status."
}

​
GET /api/v1/batch/[id]

Poll for batch status and per-job results.

​
Endpoint

GET https://lyrcs.ai/api/v1/batch/{batch_id}

​
Batch status values

StatusMeaning
queuedReceived — coordinator not yet started
in_progressJobs are fanning out and processing
completeAll jobs finished successfully
partialDone — but at least one job failed or timed out

​
Response

{
  "batch_id": "b1a2t3c4-...",
  "status": "complete",
  "job_count": 3,
  "completed": 2,
  "failed": 1,
  "pending": 0,
  "created_at": "2024-01-01T00:00:00.000Z",
  "completed_at": "2024-01-01T00:02:15.000Z",
  "jobs": [
    {
      "job_id": "a1b2c3d4-...",
      "language": "Hindi",
      "status": "complete",
      "align_requested": true,
      "review_required": false,
      "review_url": null,
      "review_approved_at": null,
      "completed_at": "2024-01-01T00:01:45.000Z",
      "studio_url": "https://lyrcs.ai/studio/a1b2c3d4-...",
      "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"
      }
    },
    {
      "job_id": "b2c3d4e5-...",
      "language": "Tamil",
      "status": "failed",
      "align_requested": true,
      "review_required": false,
      "review_url": null,
      "review_approved_at": null,
      "completed_at": null,
      "studio_url": "https://lyrcs.ai/studio/b2c3d4e5-..."
    }
  ]
}
downloads is only present on jobs where status === "complete" AND align_requested === true. Failed jobs and align=false jobs do not include it.

​
Examples

# Submit batch
curl -X POST https://lyrcs.ai/api/v1/batch \
  -H "Authorization: Bearer $LYRCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://api.example.com/webhooks/lyrcs",
    "jobs": [
      { "audio_url": "https://cdn.example.com/song-1.mp3", "language": "Hindi" },
      { "audio_url": "https://cdn.example.com/song-2.mp3", "language": "Tamil" },
      { "audio_url": "https://cdn.example.com/song-3.mp3", "language": "Telugu" }
    ]
  }'

# Poll batch status
curl https://lyrcs.ai/api/v1/batch/b1a2t3c4-... \
  -H "Authorization: Bearer $LYRCS_API_KEY"
See the Batch Processing guide for patterns on handling partial failures and polling strategy.