# Karadeo API — Agent Skill

> Use this skill to transcribe audio/video to timed subtitle files, or align any text to audio using forced alignment.
> Base URL: `https://karadeo.com`
> Auth: `Authorization: Bearer <API_KEY>` — keys issued at https://karadeo.com/dashboard

---

## Endpoint

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

### Request body

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `fileUrl` | string (URI) | yes | — | Publicly accessible URL of the audio or video file |
| `transcriptText` | string | no | — | Text to align with the audio (speech, lyrics, narration). 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). Supported by all formats except SRT |

### 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": "File duration exceeds remaining credits.",
  "usage": {
    "tier": "free",
    "usedMinutes": 8,
    "limitMinutes": 10,
    "remainingMinutes": 2,
    "mediaDurationMinutes": 5
  }
}
```

---

## Two modes

### 1. Forced alignment (transcriptText provided)

Aligns any provided text to the audio. Works with lyrics, speech transcripts, narration — any plain text.

```json
{
  "fileUrl": "https://example.com/speech.mp4",
  "transcriptText": "Hello world\nThis is line two",
  "isWordLevel": true,
  "format": "lrc"
}
```

### 2. Automatic transcription (no transcriptText)

Runs AI speech-to-text and returns a timed subtitle file.

```json
{
  "fileUrl": "https://example.com/podcast.mp3",
  "format": "srt"
}
```

Use `"format": "txt"` for plain text with no timestamps.

---

## Credits

- Cost = audio duration rounded up to the nearest minute (e.g. 61 s = 2 min)
- On failure (`500`), no credits are consumed

| Tier | Monthly limit | Reset |
|---|---|---|
| free | 10 min | 1st of each calendar month (UTC) |
| subscribed (monthly) | 500 min | Billing cycle start date |
| subscribed (annual) | 6,000 min | Billing cycle start date |

---

## Error reference

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