# NeteaseCloudMusicApiEnhanced/api-enhanced: Install and Use

> NeteaseCloudMusicApiEnhanced/api-enhanced is a Node.js API service for NetEase Cloud Music, with direct SDK calls, an HTTP server, TypeScript declarations and Docker deployment. It suits developers building self-hosted music clients or automation services, but authentication, proxy configuration and availability of the upstream service remain important constraints.

**NeteaseCloudMusicApiEnhanced/api-enhanced** — 🔍  网易云音乐 Node.js  API Services (Half Refactor & Enhanced) 全网最全的网易云音乐API接口

- Repository: https://github.com/NeteaseCloudMusicApiEnhanced/api-enhanced
- Website: http://docs-neteasecloudmusicapi.focalors.ltd/
- Stars: 2,061 · Forks: 3,360
- Language: JavaScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/neteasecloudmusicapienhanced-api-enhanced

## What api-enhanced Adds to NetEase Cloud Music Development

NeteaseCloudMusicApiEnhanced/api-enhanced packages NetEase Cloud Music operations as a Node.js API service. The documented feature set includes login, registration and verification; user profiles, playlists, activity and listening history; songs, albums, artists, music videos, lyrics, comments and charts; search, recommendations, private FM, check-in and cloud storage. It also attempts to unlock greyed songs through its song-unlocking feature.

The intended users are developers creating self-hosted music services, desktop or multi-platform clients, personal tools and secondary applications. The service can be used in two ways. Developers can start the Express application and call its HTTP endpoints, or import functions from `@neteasecloudmusicapienhanced/api` into a Node.js program. Repository entries such as `module/`, `main.js`, `app.js`, `server.js`, `interface.d.ts` and the `module_example/` directory reflect that split between endpoint modules, server entry points and direct-call examples.

This is not an official NetEase service. Its value comes from exposing a wide collection of operations through a developer-facing interface, including support for request encryption code associated with eapi, weapi and xeapi. The project also identifies `Binaryify/NeteaseCloudMusicApi` as its base. That inheritance matters when evaluating compatibility because module names, request parameters and response shapes originate in the same API ecosystem.

## HTTP Server, Node Functions and TypeScript Data Flow

The package publishes `main.js` as its CommonJS entry point and `interface.d.ts` as its TypeScript declaration file. A direct function call receives an options object and returns a Promise. The README example sends a phone number and password to `login_cellphone`, reads the cookie from the returned body, and passes that cookie into `user_cloud`. This makes the credential flow visible: the login result supplies state used by the next request.

The server package exposes `app.js` as both a package binary and the default application entry point. `server.js`, `server.test.js` and `app.js` separate network serving from package-level behavior, while `index.js` and `index.mjs` provide additional module entry points. Endpoint implementations are organized under `module/`, with configuration and request helpers elsewhere in `util/`, plugins and scripts. Static assets and API documentation are held under `public/`.

Environment settings alter processing before a request reaches the upstream service. `CORS_ALLOW_ORIGIN` controls accepted browser origins and defaults to `*`. `ENABLE_PROXY` and `PROXY_URL` enable the project's reverse-proxy feature. `ENABLE_GENERAL_UNBLOCK` defaults to `true`, causing songs to be attempted through automatic unlocking. `ENABLE_FLAC` also defaults to `true`, while `SELECT_MAX_BR` controls whether the highest bitrate is selected. `FOLLOW_SOURCE_ORDER` defaults to `true`, so matching follows the configured source order.

The README does not describe a stability contract for upstream endpoint shapes. Response processing is documented, but the project's compatibility with every NetEase service change is not guaranteed.

## Installing api-enhanced and Making a First SDK Call

The documented local requirement is Node.js 22 or later, with pnpm recommended for dependency management. Clone the repository, enter its directory and install the locked project dependencies:

```bash
git clone https://github.com/neteasecloudmusicapienhanced/api-enhanced.git
cd api-enhanced
pnpm i
```

A first direct call can be made from a Node.js project after installing the published package. The following example is reproduced from the README. It performs a phone login and then requests the user's cloud data with the returned cookie.

```js
const {
  login_cellphone,
  user_cloud,
} = require('@neteasecloudmusicapienhanced/api')
async function main() {
  const result = await login_cellphone({ phone: '手机号', password: '密码' })
  console.log(result)
  const result2 = await user_cloud({ cookie: result.body.cookie })
  console.log(result2.body)
}
main()
```

The reader should replace the Chinese placeholders with actual values and run this from a project that can resolve the package. The README does not document a special installation command for the npm package, so it provides the repository installation instructions and links to `@neteasecloudmusicapienhanced/api` on npm. The example also demonstrates why cookie handling deserves attention: the result of one authenticated operation becomes input to another.

TypeScript projects can use the package's declarations with a named import:

```ts
import { banner } from '@neteasecloudmusicapienhanced/api'
banner({ type: 0 }).then((res) => console.log(res))
```

The package declares `interface.d.ts` as its `types` entry. That supports typed integration, although the repository information does not promise compatibility with every NetEase response variant.

## Starting the API Server on Port 3000

After installing dependencies, start the application with the start script or the Node command shown in the README. The default listening port is 3000:

```bash
node app.js
```

For a different port, the README provides separate commands for Mac/Linux and Windows:

```bash
PORT=4000 node app.js
```

```bash
set PORT=4000 && node app.js
```

The first form assigns `PORT` in the shell before starting Node. The second uses the Windows `set` syntax. The documentation does not provide a sample raw HTTP request with an exact route, query string and expected response, so it would be misleading to invent one. A first direct SDK call is therefore the clearest documented use, while endpoint-specific testing requires the linked online documentation and its required pre-call notes.

The `package.json` development command is `pnpm dev`, which invokes `nodemon app.js`. That is useful during local development, but the README's first-use path uses `node app.js`. Automated tests are exposed through `pnpm test`, with a Mocha timeout of 60000 milliseconds according to the package script. These checks should not be treated as proof that external NetEase requests will always succeed.

## Docker Deployment and Proxy Failure Modes

The project publishes a Docker image and documents direct installation as the shortest deployment path:

```shell
docker pull moefurina/ncm-api:latest

docker run -d -p 3000:3000 --name ncm-api moefurina/ncm-api:latest
```

The `Dockerfile` uses `node:lts-alpine`, installs pnpm 9, runs a frozen production install with scripts disabled, exposes port 3000 and starts `node app.js` through `tini`. This removes the need to install Node.js on the host, but `:latest` does not pin the application version. The package information identifies 4.41.1 as the current repository version, while the upgrade procedure shown in the README pulls `latest` again.

Proxy behavior is a genuine operational constraint. The README states that Docker deployment checks proxy-related environment variables used by `request`. An unavailable configured proxy causes errors. A `proxy` query parameter overrides those environment variables. The documented variables are:

```shell
http_proxy
https_proxy
HTTP_PROXY
HTTPS_PROXY
no_proxy
NO_PROXY
```

To run the container with those values blank, the README shows both named and unnamed container variants:

```shell
docker run -d -p 3000:3000 --name ncm-api -e http_proxy= -e https_proxy= -e no_proxy= -e HTTP_PROXY= -e HTTPS_PROXY= -e NO_PROXY= moefurina/ncm-api:latest
```

The documentation is explicit about proxy selection, but it does not provide a complete network-policy or firewall guide. A deployment can therefore start successfully and still fail when upstream requests cannot pass through its configured route.

## Maintenance, Releases, Licensing and Upgrade Boundaries

The repository is not archived, and its last push was on 2026-10-14. Recent releases include v4.41.1 on 2026-10-05, v4.41.0 on 2026-10-03 and v4.40.1 on 2026-08-18. Those dates show recent repository activity, but they do not establish that every endpoint has a stable upstream contract. Version 4.41.1 in `package.json` aligns with the newest listed release.

The Docker update procedure is small but disruptive because it replaces the running container:

```bash
docker pull moefurina/ncm-api:latest
docker stop ncm-api && docker rm ncm-api
docker run -d -p 3000:3000 moefurina/ncm-api:latest
```

The project uses the MIT License. The README says the code may be used, modified and distributed, including for commercial purposes, without warranty. That is the project's licensing statement rather than legal advice. Deployers still need to account for account credentials, cookies, service terms and any separate rights associated with music content or use of the upstream platform.

The README also says the original `Binaryify/NeteaseCloudMusicApi` npm package remains maintained and points readers to its npm page. It says that original GitHub repository no longer updates. For a new deployment, api-enhanced is the reviewed project, but teams migrating from the original package should compare exported functions and response handling rather than assuming package names are the only difference.

## When api-enhanced Is the Wrong Choice

api-enhanced is a poor fit for an application that requires a guaranteed official service-level agreement. The README calls it a free project and explicitly provides no warranty. It is also unsuitable as an offline music catalog: the documented functions submit requests to NetEase Cloud Music and optionally send traffic through proxies, so the service still depends on upstream availability and network access.

Browser-only applications should not expose the default permissive CORS configuration without review. `CORS_ALLOW_ORIGIN` defaults to `*`, which permits any origin according to the configuration table. The README recommends placing sensitive information such as cookies in deployment environment variables, but it does not describe a complete secret-rotation or cookie-storage design. Authentication code must therefore be evaluated as part of the deployment, not treated as an incidental example.

A lightweight static website that only links to public music pages does not need this project. Its server process, account flows, unlock settings and audio-quality options add more moving parts than such a site requires. For a multi-client backend or a Node.js application needing direct API functions, the structure is more appropriate, provided proxy routing and authenticated operations are acceptable dependencies.

## Conclusion

Adopt api-enhanced when you need a broad NetEase Cloud Music API surface, direct Node.js functions or a self-hosted Express service. Do not choose it if undocumented upstream changes, account handling or network routing would make your application unpredictable. Before adoption, verify the required account and cookie flow, the endpoint documentation, proxy variables and the exact release or image tag your deployment will pin.

## FAQ

### What Node.js version does NeteaseCloudMusicApiEnhanced/api-enhanced require?

The README requires Node.js 22 or later and recommends pnpm for dependency management.

### Can I call NeteaseCloudMusicApiEnhanced/api-enhanced as a Node.js package?

Yes. The package exposes CommonJS functions that return Promises, and it also provides `interface.d.ts` for TypeScript integration.

### Which port does the NeteaseCloudMusicApiEnhanced/api-enhanced Docker container use?

The documented Docker command publishes port 3000, and the `Dockerfile` exposes 3000 before starting `node app.js`.

## Sources

- [License: MIT](https://github.com/NeteaseCloudMusicApiEnhanced/api-enhanced/blob/main/LICENSE)
- [NeteaseCloudMusicApiEnhanced/api-enhanced on GitHub](https://github.com/NeteaseCloudMusicApiEnhanced/api-enhanced)
- [Project website](http://docs-neteasecloudmusicapi.focalors.ltd/)
- [README](https://github.com/NeteaseCloudMusicApiEnhanced/api-enhanced/blob/main/README.md)
- [Releases](https://github.com/NeteaseCloudMusicApiEnhanced/api-enhanced/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/neteasecloudmusicapienhanced-api-enhanced