Native Endpoints

Native endpoints for the AMLL lyric database, providing full search and matching capabilities.

Search Lyrics

Search lyrics matching specified conditions in the database.

GET/v1/lyrics/search

Query Parameters

At least one of the following parameters must be provided. Multiple parameters can be combined to increase precision:

If q is passed along with other parameters, q will be ignored in favor of specific field parameters.
Multiple non-q parameters use AND (intersection) logic.
Empty string parameters are treated as not provided.
musicName, artistName, and albumName are recommended over q for higher precision.

Parameter	Type	Match Logic	Description
`q`	`string`	Fuzzy contains	Search across song titles, artists, albums, and lyric text
`musicName`	`string`	Fuzzy contains	Match song title
`artistName`	`string`	Fuzzy contains	Match artist name
`albumName`	`string`	Fuzzy contains	Match album title
`lyricText`	`string`	Full-text search	Case-insensitive match on lyric text
`authorId`	`string`	Exact match	TTML contributor GitHub ID
`authorUsername`	`string`	Exact match	TTML contributor GitHub username

Pagination Parameters

The following parameters control paging and are all optional. They do not count toward the “at least one search parameter” requirement above, and they do not affect the priority resolution between q and the other parameters.

Parameter	Type	Default	Range	Description
`page`	`number`	`1`	`>= 1`	Page number, starting at 1
`pageSize`	`number`	`50`	`1`–`100`	Number of items per page

Non-positive integers, 0, or values outside the allowed range return 400.
An empty value (e.g. ?page=) is treated as not provided and falls back to the default.
Passing only pagination parameters without any search parameter still returns 400.

Response Behavior

Results are sorted by relevance descending, then by timestamp descending when relevance is tied, then by id ascending when both are tied.
The ordering is stable: repeated requests with the same query return consistent pages, with no duplicates or gaps between adjacent pages.

Response Schema

Returns 200 status code on success with the following structure:

export interface PaginationInfo {
  /** Current page number */
  page: number;
  /** Number of items per page */
  pageSize: number;
  /** Total number of matched items */
  total: number;
  /** Total number of pages; `0` when `total` is `0` */
  totalPages: number;
  /** Whether more results exist after the current page */
  hasMore: boolean;
}

type SearchLyricsResponse = ApiResponse<{
  items: SongItem[];
  pagination: PaginationInfo;
}>;

Field Descriptions:

ApiResponse<T>: Global generic response wrapper structure, see ApiResponse Model
items: List of matched songs, element type is SongItem Model
- lyrics is fixed to undefined for each item in search results.
- matchContext is present with highlighted snippet only when the query matches lyric text.
- Length never exceeds pageSize; the last page may contain fewer items.
pagination: Object containing pagination metadata for the current request, see PaginationInfo Model
- page: Current page number
- pageSize: Number of items per page
- total: Total number of items matching the current query, unaffected by page / pageSize
- totalPages: Total number of pages, 0 when total is 0
- hasMore: Equivalent to page < totalPages; can be used directly to decide whether to request the next page
When the requested page exceeds totalPages, items is an empty array while the other fields are returned as usual.

Example Response

{
  "status": 200,
  "data": {
    "items": [
      {
        "id": 8713122671638320,
        "filename": "1702791169000-50747104-65652a93.ttml",
        "musicNames": [
          "ME! (feat. Brendon Urie of Panic! At The Disco)"
        ],
        "artistNames": [
          "Taylor Swift",
          "Brendon Urie"
        ],
        "albumNames": [
          "ME! (feat. Brendon Urie of Panic! At The Disco)"
        ],
        "ncmMusicIds": [
          "1361348080"
        ],
        "qqMusicIds": [],
        "appleMusicIds": [],
        "spotifyIds": [],
        "isrcs": [],
        "authorIds": [
          "50747104"
        ],
        "authorUsernames": [
          "Xionghaizi001"
        ],
        "matchContext": {
          "snippet": "I never want to see you walk away\n<mark>'Cause one of these things is not like the others</mark>\nLiving in winter I am your summer"
        }
      },
      {
        "id": 8489623513658892,
        "filename": "1689481280000-132769718-1028454c.ttml",
        "musicNames": [
          "ME! (feat. Brendon Urie of Panic! At The Disco)"
        ],
        "artistNames": [
          "Taylor Swift",
          "Brendon Urie"
        ],
        "albumNames": [
          "ME! (feat. Brendon Urie of Panic! At The Disco)"
        ],
        "ncmMusicIds": [
          "1361348080"
        ],
        "qqMusicIds": [],
        "appleMusicIds": [],
        "spotifyIds": [],
        "isrcs": [],
        "authorIds": [
          "132769718"
        ],
        "authorUsernames": [
          "Y-CIAO"
        ],
        "matchContext": {
          "snippet": "And there's a lot of lame guys out there\n<mark>'Cause one of these things is not like the others</mark>\nLiving in winter I am your summer"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "total": 2,
      "totalPages": 1,
      "hasMore": false
    }
  }
}

Get Lyric

Get song metadata and full TTML lyrics by ID or parameters.

GET/v1/lyrics/get

Query Parameters

At least one of the following parameters must be provided.

Parameter Priority:

id has the highest priority: other parameters are ignored when present.
filename has second highest priority: platform ID parameters are ignored when present.
If only platform IDs from multiple platforms are provided, an intersection match will be performed, returning only the single newest matching result. To get older versions, use id or filename.

Parameter	Type	Required	Description
`id`	`number`	No	53-bit integer ID generated from filename, exact match
`filename`	`string`	No	Lyric filename, exact match. Must end with `.ttml`
`ncmMusicId`	`string[]`	No	Netease Cloud Music ID
`qqMusicId`	`string[]`	No	QQ Music ID
`appleMusicId`	`string[]`	No	Apple Music ID
`spotifyId`	`string[]`	No	Spotify ID
`isrc`	`string[]`	No	ISRC code
`format`	`string`	No	Reserved field, defaults to `ttml`. Other values return 400

Response Schema

Returns 200 status code on success with the following structure:

type GetLyricResponse = ApiResponse<SongItem>;

Related Model Description:

ApiResponse<T>: Generic response wrapper, see ApiResponse Model
data: Song metadata and complete lyric object of type SongItem Model, containing full lyrics TTML string

Example Response

{
  "status": 200,
  "data": {
    "id": 269710089745311,
    "filename": "1768754400682-250306205-r6IrpmBd.ttml",
    "musicNames": [
      "ME!",
      "ME! (feat. Brendon Urie of Panic! At The Disco)"
    ],
    "artistNames": [
      "Brendon Urie",
      "Taylor Swift"
    ],
    "albumNames": [
      "Lover"
    ],
    "ncmMusicIds": [
      "1361348080",
      "1382781549"
    ],
    "qqMusicIds": [
      "0032UZe62rZk9K"
    ],
    "appleMusicIds": [
      "1468058706"
    ],
    "spotifyIds": [
      "2Rk4JlNc2TPmZe2af99d45"
    ],
    "isrcs": [
      "USUG11901494"
    ],
    "authorIds": [
      "108002475",
      "132769718",
      "207428447",
      "250306205",
      "34237075",
      "50747104"
    ],
    "authorUsernames": [
      "SteamFinder",
      "Xionghaizi001",
      "Y-CIAO",
      "apoint123",
      "kid1412520",
      "kid141252010"
    ],
    "lyrics": "<omitted>",
    "format": "ttml"
  }
}