# QuickLRC API — Agent Skill

> Use this skill to generate time-synced lyrics and subtitle files from any audio, video, or YouTube URL.
> Base URL: `https://quicklrc.com`
> Auth: `Authorization: Bearer <API_KEY>` — keys issued at https://quicklrc.com/dashboard

---

## Endpoint

```
POST /api/v1/transcribe
Content-Type: application/json
Authorization: Bearer <API_KEY>
```

### Request body

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `fileUrl` | string (URI) | yes | — | Public audio/video URL or YouTube URL |
| `lyrics` | string | no | — | Plain-text lyrics for forced alignment (omit for automatic speech-to-text) |
| `format` | string | no | `lrc` | Output format: `lrc`, `srt`, `webvtt`, `ass`, `ttml`, `txt` |
| `isWordLevel` | boolean | no | `false` | Embed per-word timestamps (karaoke-style) |
| `smartSections` | boolean | no | `false` | Auto-insert section labels like `[Verse 1]`, `[Chorus]` |

### Response

`200 OK` — subtitle file as plain text (Content-Type matches requested format)

Error responses return JSON `{ "error": "..." }`. A `402` or `403` also includes a `usage` object:

```json
{
  "error": "Media duration exceeds remaining credits.",
  "usage": {
    "usedMinutes": 10,
    "limitMinutes": 60,
    "remainingMinutes": 50,
    "mediaDurationMinutes": 5
  }
}
```

---

## Two modes

### 1. Forced alignment (lyrics provided)

Aligns the given lyrics text to the audio. Use this when you already know the lyrics.

```json
{
  "fileUrl": "https://example.com/song.mp3",
  "lyrics": "Hello world\nThis is line two",
  "format": "lrc"
}
```

### 2. Automatic transcription (no lyrics)

Runs AI speech-to-text and returns timed output. Works with music, speech, and YouTube URLs.

```json
{
  "fileUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "format": "srt",
  "isWordLevel": true,
  "smartSections": true
}
```

---

## Credits

- 60 credits = 1 minute of audio
- Credits are deducted per request, rounded up to the nearest minute
- On failure (`500`), no credits are consumed
- Check remaining credits in the dashboard or handle `402`/`403` responses

---

## Error reference

| Status | Meaning |
|---|---|
| `400` | Missing `fileUrl`, unsupported format, or unresolvable audio duration |
| `401` | Missing or invalid API key |
| `402` | This file exceeds your remaining credits |
| `403` | Monthly usage limit reached |
| `500` | Processing failed — not charged |

---

## Machine-readable specs

- OpenAPI 3.1: `https://quicklrc.com/openapi.json`
- API catalog (RFC 9727): `https://quicklrc.com/.well-known/api-catalog`