KuGouMusicApi wraps a music platform's private API behind a Node service

How it works is three steps and not much more

The description of the mechanism is unusually short: cross-site request forgery, forged request headers, and calls to the official API. Everything in the codebase follows from that. Because the platform's own mobile app authenticates with a CSRF token and a set of client fingerprint headers, the service reproduces that handshake and then replays the requests. The requests are made with axios, and the responses are parsed and re-served as JSON over Express. The dependency list in the package manifest is the fingerprint of the approach: pako for compressed payloads, node-forge and crypto-js for the signature and encryption work, big-integer for the arithmetic the platform's algorithms need, qrcode and form-data for the login and upload paths, and safe-decode-uri-component for the callback URLs. The project credits the NeteaseCloudMusicApi repository as its inspiration.

Device identity is configured, not generated

The environment file is where the interesting configuration lives, and three of its variables are about pretending to be a specific handset. There is a device id, `KUGOU_API_GUID`, which the file recommends be a uuidv4, a `KUGOU_API_DEV` string suggested to be ten characters long, and a MAC address. Then there is `KUGOU_API_WEBGL`, a browser fingerprint value such as 9655615838832711846, and the file points at a generator page, `public/sid_edt_generator.html`, for obtaining a fixed one. The comments mark the identifier and device id as optional but recommend fixing them, which is the key operational point: a stable identifier means the platform sees a returning client rather than a new one on every request. The repository also ships a `public/` directory, so that generator page is part of the distribution rather than something you write yourself.

Two platform versions, and tokens do not cross between them

The single most consequential setting is `platform`. The environment file sets it to an empty string, and the comment says the default is the mobile app version while `lite` is the concept version of the app. The usage note is blunt about the consequence: tokens from different platform versions are not interchangeable, and the interface is described as a conceptual version. The deployment instructions mark this as a step you can skip if you do not need the concept version. So before anything works you have to decide which platform you are emulating, obtain credentials for that platform, and keep using that one. Switching platforms mid-session invalidates the session, which is the kind of error that looks like a random authentication failure rather than a configuration mistake.

Running it locally is npm install and npm run dev

The setup is the ordinary Node one. You clone the repository, change into it, and install the dependencies:

$ git clone [email protected]:MakcRe/KuGouMusicApi.git
$ cd KuGouMusicApi
$ npm install

Then you copy the environment example to a real environment file and set the platform, and start the development server:

$ npm run dev

The dev script runs nodemon against `index.js` with a nodemon configuration file, while the production entry is `node app.js`. The server listens on port 3000 by default and the host defaults to localhost, and both can be overridden with environment variables. The documentation gives the per-shell syntax for that, which is a small sign of care about the Windows case, and the proxy variable is handled the same way. If you need to reach the platform through an HTTP proxy, the `KUGOU_API_PROXY` environment variable is read at startup, and the same thing can be done as a command line argument to `app.js`.

A hundred and thirty two endpoints, and a deliberate naming split

The endpoint list is the bulk of the documentation, and it is organised by area: login, refreshing the session, sending a verification code, and getting a device id, then the user area with extra user info, VIP status, playlists, followed artists, listening history and the continue-playing information that matches the mobile home screen. The media area covers new releases, album information and detail, album track lists, dynamic cover art, music URLs, and the highlight portion of a song. The search area has the basic search, default keywords, comprehensive search, hot search list, search suggestions and lyric search, and the lyrics endpoint. The rest covers playlists and their categories, the theme and sound-effect playlist variants, artist information and images, similar playlists, recommendations, private FM, banners, the editorial picks section, rankings with their history, comments at several levels, and sheet music with its own detail and collection endpoints, plus a channels area and an audiobook area with its own rankings and free library.

Deployment is a Vercel import and a Dockerfile

There are two deployment paths, one serverless and one container. The Vercel route is a fork, a new project, an import of the git repository, and a framework preset of Other, with the platform environment variable set to lite if you want the concept version. The container route is a Dockerfile based on the Node LTS Alpine image, with tini added as the init process, corepack enabled so pnpm is available, the app directory chowned to the node user, a production-only frozen-lockfile install, port 3000 exposed, and the entrypoint running tini with `node app.js`. The non-root user handling and the frozen lockfile are the details that separate a careful image from a casual one. There is also a `vercel.json` at the root and a `pnpm-lock.yaml`, so the project supports pnpm as well as npm even though the documented install path uses npm.

The disclaimer is longer than most of the usage instructions

The legal section is the most substantial prose in the documentation, and it is worth taking seriously because it sets the terms of use rather than describing them. The project states it is for study only, that copyright should be respected, and that it should not be used for commercial or illegal purposes. It notes that using it may produce copyrighted data, that the project does not own that data, and that users must clear it within 24 hours. Liability for any direct or indirect damage, including lost goodwill and business interruption, is placed on the user, and using the project in violation of local law is explicitly the user's responsibility. The project refuses commercial cooperation including advertising and donations, and says the platform operators may ask for the project to be changed or removed. The section also asks users to respect copyright and support legitimate purchasing.

Editorial conclusion

Adopt KuGouMusicApi if you are studying how mobile apps authenticate against private APIs, since the CSRF handling, header forging and device fingerprint configuration are the interesting part and the code is short enough to read in an afternoon. Do not adopt it as the backing of a product that serves music to end users, because the service returns copyrighted material and the project's own disclaimer limits use to study and research and puts the burden of clearing the data on whoever runs it. Verify first that the platform setting you choose matches the tokens you have, since the documentation warns that tokens are not shared between platform versions, and read the disclaimer before you install anything.

Frequently asked questions

Official sources

1. License: MIT
2. MakcRe/KuGouMusicApi on GitHub
3. Project website
4. README
5. Releases