API Documentation

Developer documentation for the Kaemit download API, lyrics API, and website token access.

/download

Download API

Download audio or video from a YouTube URL in your chosen format and quality.

/lyric

Lyrics API

Retrieve synchronized or plain lyrics by song title with an optional artist filter.

/login

Website Tokens

GET /login

Token login is browser-session based and only affects downloads made through the Kaemit website UI.

Valid tokens are managed server-side and are used only for browser-session login.

When logged in, website requests bypass Flask-Limiter download limits and the 50-track playlist download cap. API requests do not support token headers, bearer tokens, or token parameters.

Download API

POST /download

Downloads audio or video from YouTube and returns the converted file as a binary attachment. Accepts a JSON body.

Request Body

Parameter	Type		Description
url	string	required	YouTube video URL (`youtube.com` or `youtu.be`)
type	string	optional	`audio` (default) or `video`
format	string	optional	Audio: `flac` (default), `mp3`, `aac`, `wav`, `ogg`, `opus`, `m4a` Video: `mp4`, `mkv`, `webm`, `mov`, `avi`
naming	string	optional	`title` (default), `artist_title`, `title_artist`, `title_id`, or `artist_title_id`
filename	string	optional	Exact custom filename for single downloads only. Any supplied extension is replaced with the selected output format.

Rate limit: 5/minute and 20/hour. Website token login does not apply to direct API clients.

Example

curl -X POST "http://kaemit.cc/download" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://youtu.be/ARtruzEKSBw","type":"audio","format":"flac"}' \
  --output song.flac

On success the binary file is returned. On error:

{ "error": "Only YouTube URLs are supported" }

Lyrics API

GET /lyric

Returns raw LRC-format lyrics or plain text from available lyric sources. Lyrics are also automatically embedded into audio file metadata on download.

Query Parameters

Parameter	Type		Description
q	string	required	Song title or alias
artist	string	optional	Filter by artist name — improves search accuracy

Example

curl "http://kaemit.cc/lyric?q=Broken+Script&artist=Noyuri"

Returns the raw lyrics text — LRC format when synced is available, plain text otherwise. 404 when not found.

Rate limit: 30/minute. Website tokens do not apply to this endpoint.

Error Codes

Code	Meaning
400	Bad Request — missing or invalid parameters
404	Not Found — lyrics not found for the given query
422	Unprocessable — video unavailable, age-restricted, or private
429	Too Many Requests — public API or free website rate limit exceeded
500	Server Error — FFmpeg missing or unexpected failure