API Documentation – AI LRC Generator

Documentation – LRC Generator & Lyrics File Maker

API Documentation

Generate time-synced LRC lyric files from audio/video programmatically using the AI LRC Generator API.

Overview

The AI LRC Generator API lets you upload audio/video files and receive time-synced LRC lyrics asynchronously. The typical flow is:

Upload + trigger — POST /api/v2/open/audio_analysis (one-step, recommended)
Poll for result — GET /api/v2/open/audio_tasks/:id until status is COMPLETED

Base URL: https://ailrcgenerator.com

Authentication

All requests require an API key in the Authorization header.

Authorization: Bearer ailrc_sk_YOUR_KEY

Create and manage your API keys on the Developer API page. Keys are shown only once at creation — save them immediately.

Treat your API key like a password. Never expose it in client-side code or public repositories.

Rate Limits

The API is currently in public beta. Limits may change based on service capacity and actual usage. For higher-throughput requirements, please contact support.

General request limits are a high-ceiling abuse safeguard covering task submission, task lists, status polling, and other Open API calls. They use a three-layer sliding window (minute / hour / day); hitting any layer returns 429.

Tier	Per Minute	Per Hour	Per Day
Free	30	600	3,000
Pro	300	6,000	30,000
Premium	1,000	20,000	100,000

Analysis submissions are the primary tier limit. Only POST /api/v2/open/audio_analysis counts toward these limits:

Tier	Per Minute	Per Hour	Per Day	In Flight
Free	3	20	50	1
Pro	60	1,000	5,000	3
Premium	200	4,000	20,000	5

Rate limit state is returned on every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1745024400

Exceeding the limit returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

Endpoints

Trigger Analysis

Upload an audio/video file and immediately start AI analysis (one-step mode).

POST /api/v2/open/audio_analysis
Content-Type: multipart/form-data

Request

Field	Type	Required	Notes
`file`	File	✓	mp3, wav, ogg, flac, mp4, webm, mov
`fileName`	string	—	Custom file name; falls back to original if omitted
`metadata`	JSON string	—	AI analysis options serialized as JSON

metadata fields

Field	Type	Default	Notes
`enableMetadata`	boolean	`true`	Use embedded audio metadata when generating lyrics
`reference`	string	`""`	Reference lyrics or text to assist recognition
`language`	string	`auto`	Lyrics language code, or `auto` for detection
`enableChorus`	boolean	`false`	Add singer/chorus labels when supported
`enableTranslation`	boolean	`false`	Generate translated lyrics together with the original
`sourceLanguage`	string	`auto`	Translation source language code, or `auto`
`targetLanguage`	string	—	Required when `enableTranslation` is `true`

Size limits by tier: Free 10 MB · Pro 30 MB · Premium 60 MB

Example

curl -X POST https://ailrcgenerator.com/api/v2/open/audio_analysis \
  -H "Authorization: Bearer ailrc_sk_YOUR_KEY" \
  -F "[email protected]" \
  -F "fileName=My Song" \
  -F 'metadata={"enableMetadata":true,"reference":"","language":"auto","enableChorus":false,"enableTranslation":true,"sourceLanguage":"auto","targetLanguage":"en"}'

Response

{
  "code": 0,
  "message": "ok",
  "items": {
    "taskId": "cm4abc123",
    "traceId": "cm4abc123",
    "status": "QUEUED",
    "queuePosition": 2,
    "remainingCredits": 46,
    "fileName": "song.mp3"
  }
}

Get Task Status

Fetch the current status and result of a task. Poll this endpoint until status is COMPLETED or FAILED. See Polling Guide for recommended intervals.

GET /api/v2/open/audio_tasks/:id

Example

curl https://ailrcgenerator.com/api/v2/open/audio_tasks/cm4abc123 \
  -H "Authorization: Bearer ailrc_sk_YOUR_KEY"

Response fields

Field	Type	Returned when	Notes
`taskId`	string	Always	Analysis task ID
`fileName`	string	Always	Uploaded file name
`status`	string	Always	`PENDING`, `QUEUED`, `PROCESSING`, `COMPLETED`, or `FAILED`
`queuePosition`	number/null	Queued	Current queue position when available
`progress`	number	Processing	Processing progress reported by the worker
`result`	object	Completed	Contains the generated `lrc` text
`error`	string	Failed	Normalized public error message
`creditsUsed`	number	Completed	Credits charged for the task
`completedAt`	string	Completed	ISO 8601 completion time
`audioFileUrl`	string/null	Always	Presigned audio URL; expires after 24 hours and may be `null` if signing fails

Response — queued

{
  "code": 0,
  "items": {
    "taskId": "cm4abc123",
    "status": "QUEUED",
    "queuePosition": 2,
    "audioFileUrl": "https://storage.example.com/presigned-audio-url",
    "fileName": "song.mp3"
  }
}

Response — in progress

{
  "code": 0,
  "items": {
    "taskId": "cm4abc123",
    "status": "PROCESSING",
    "progress": 35,
    "audioFileUrl": "https://storage.example.com/presigned-audio-url",
    "fileName": "song.mp3"
  }
}

Response — completed

{
  "code": 0,
  "items": {
    "taskId": "cm4abc123",
    "status": "COMPLETED",
    "result": {
      "lrc": "[00:00.00]Line one\n[00:05.23]Line two\n[00:10.40]Line three"
    },
    "creditsUsed": 6,
    "completedAt": "2026-04-19T10:02:30Z",
    "audioFileUrl": "https://storage.example.com/presigned-audio-url",
    "fileName": "song.mp3"
  }
}

Response — failed

{
  "code": 0,
  "items": {
    "taskId": "cm4abc123",
    "status": "FAILED",
    "error": "PROCESSING_FAILED",
    "audioFileUrl": "https://storage.example.com/presigned-audio-url",
    "fileName": "song.mp3"
  }
}

List Tasks

Return a paginated list of your audio tasks.

GET /api/v2/open/audio_tasks

Query parameters

Parameter	Default	Notes
`page`	`1`	Page number
`limit`	`20`	Max `100` per page
`status`	—	Filter: `PENDING` `QUEUED` `PROCESSING` `COMPLETED` `FAILED`

Example

curl "https://ailrcgenerator.com/api/v2/open/audio_tasks?page=1&limit=20&status=COMPLETED" \
  -H "Authorization: Bearer ailrc_sk_YOUR_KEY"

Delete Task

Delete a task and its associated data.

DELETE /api/v2/open/audio_tasks/:id

Tasks with status PROCESSING or QUEUED cannot be deleted.

Example

curl -X DELETE https://ailrcgenerator.com/api/v2/open/audio_tasks/cm4abc123 \
  -H "Authorization: Bearer ailrc_sk_YOUR_KEY"

Error Reference

All errors use a consistent envelope:

{
  "code": 403,
  "message": "Not enough credits",
  "businessCode": "not_enough_credits"
}

HTTP	`businessCode`	Meaning
`400`	—	Bad request — missing or invalid field
`401`	—	API key is missing, invalid, revoked, or expired
`403`	`not_enough_credits`	Insufficient credits
`403`	`level_not_enough`	File exceeds the size limit for your tier
`404`	—	Task not found or does not belong to your account
`429`	—	Rate limit exceeded — check `Retry-After`
`500`	—	Internal server error

Polling Guide

AI analysis is asynchronous and typically completes within 30–120 seconds depending on file length.

Recommended strategy: start at 3 s, back off to a 10 s cap, give up after 60 attempts (~10 min).

async function pollTask(taskId, apiKey) {
  let delay = 3000;
  for (let i = 0; i < 60; i++) {
    await new Promise((r) => setTimeout(r, delay));
    const res = await fetch(
      `https://ailrcgenerator.com/api/v2/open/audio_tasks/${taskId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } },
    );
    const { items } = await res.json();
    if (items.status === "COMPLETED") return items.result.lrc;
    if (items.status === "FAILED")
      throw new Error(items.error ?? "Analysis failed");
    delay = Math.min(delay * 1.5, 10000);
  }
  throw new Error("Timed out");
}

Need help? Contact support · Webhook support coming soon.