# Introduction

The Better Lyrics API serves syllable-synced lyrics for any song, for free. It powers the [Better Lyrics](https://better-lyrics.boidu.dev/) browser extension, and you can use it in your own apps too.

## Base URL

Send every request to:

```bash
https://api.betterlyrics.org
```

## Quick start

Fetch lyrics for a song with a single GET request:

   

```bash
curl "https://api.betterlyrics.org/getLyrics?s=E85&a=Don%20Toliver&al=OCTANE&d=154"
```

```javascript
const res = await fetch("https://api.betterlyrics.org/getLyrics?s=E85&a=Don%20Toliver&al=OCTANE&d=154");
const { ttml } = await res.json();
```

```python
import requests

res = requests.get("https://api.betterlyrics.org/getLyrics?s=E85&a=Don%20Toliver&al=OCTANE&d=154")
ttml = res.json()["ttml"]
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	res, err := http.Get("https://api.betterlyrics.org/getLyrics?s=E85&a=Don%20Toliver&al=OCTANE&d=154")
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(body))
}
```

### Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `s`, `song`, or `songName` | Always send | The song title |
| `a`, `artist`, or `artistName` | Always send | The artist name |
| `al`, `album`, or `albumName` | Always send | The album name |
| `d` or `duration` | Always send | Track duration in whole seconds |

The API rejects a request (`422`) only when both song and artist are missing. Send all four anyway: the cache key includes album and duration, so a request without them often misses the cached entry and, without an API key, returns `401`.

### Response

A successful response contains TTML (Timed Text Markup Language) with syllable-level timing:

```json
{
  "ttml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>..."
}
```

## Key features

-   Free to use. Cached responses need no API key, and most use cases have no usage limits
-   Syllable-level sync, with a start and end time for every syllable, for karaoke-style display
-   Several providers: TTML (default), Kugou and QQ, each suited to different uses
-   Heavy caching, so cache hits are free and need no API key
-   Two-tier rate limiting that keeps serving cached responses under load, even to rate-limited clients
-   A circuit breaker that protects the API from upstream failures

## Attribution

If your project uses this API, we'd appreciate a link to [Better Lyrics](https://better-lyrics.boidu.dev/). It helps other people find the project and keeps development going.

## Next steps

-   [Authentication](https://docs.betterlyrics.org/docs/authentication): API keys and when you need one
-   [Rate limiting](https://docs.betterlyrics.org/docs/rate-limiting): how the two tiers work
-   [Response format](https://docs.betterlyrics.org/docs/response-format): parse and use the TTML response
-   [Playground](https://docs.betterlyrics.org/playground): try the API in your browser

Source: https://docs.betterlyrics.org/