DOCSEARCHbyAlgolia
Submit Docs

NeteaseCloudMusicApiEnhanced

repository·main·Indexed 23 days ago

https://github.com/neteasecloudmusicapienhanced/api-enhanced

A third-party Node.js API for Netease Cloud Music, serving as a revival, refactor, and enhancement of the original NeteaseCloudMusicApi (starting from v4.28.0). It provides a wide range of music-related interfaces for self-hosted services, secondary development, and multi-platform deployment. The project supports deployment via Docker, Vercel, and Tencent Cloud Serverless, and can be used as a module in Node.js and TypeScript projects via the @neteasecloudmusicapienhanced/api package.

Tokens
20.8K
Snippets
70
Records
147
Agent score
79%

What's inside NeteaseCloudMusicApiEnhanced

  1. Deploy to Tencent Cloud Serverless

    main

    For better access within China, you can deploy to Tencent Cloud Serverless using the following steps:

    1. Fork the repository.
    2. In the Tencent Cloud Serverless console, create a new application as a Web Application using the Express framework.
    3. Select Code Repository as the upload method and authorize GitHub to select your fork.
    4. Set the Startup File to:
    #!/bin/bash
export PORT=9000
/var/lang/node16/bin/node app.js

    Note: Tencent Cloud Serverless is not free (though there is a free tier for the first three months) and will automatically associate a 'Log Service' topic which incurs costs.

  3. Run the API using Docker

    main

    You can run the API using a pre-built image or by building your own.

    Important: When running in Docker, the underlying request library checks for proxy environment variables. If these are set to invalid proxies, the container will fail. You can override these by providing the proxy query parameter in your API calls.

    Relevant environment variables: http_proxy, https_proxy, HTTP_PROXY, HTTPS_PROXY, no_proxy, NO_PROXY.

    # Pull and run pre-built image
docker pull moefurina/ncm-api
docker run -d -p 3000:3000 --name ncm-api-enhanced moefurina/ncm-api

# Run while clearing proxy environment variables to avoid errors
docker run -d -p 3000:3000 --name ncm-api-enhanced -e http_proxy= -e https_proxy= -e no_proxy= -e HTTP_PROXY= -e HTTPS_PROXY= -e NO_PROXY= moefurina/ncm-api

# Build from source
git clone https://github.com/neteasecloudmusicapienhanced/api-enhanced.git && cd api
sudo docker build . -t netease-music-api
sudo docker run -d -p 3000:3000 netease-music-api

  4. Perform QR Code Login

    main

    QR code login is a three-step process. Always include a timestamp in these requests to prevent caching issues.

    1. Generate QR Key

    Endpoint: /login/qr/key Returns a unique key for the session.

    2. Create QR Code

    Endpoint: /login/qr/create Parameters:

    • key (Required): The key from step 1.
    • qrimg (Optional): If present, returns the QR code as a base64 string.

    3. Check QR Status

    Endpoint: /login/qr/check Parameters:

    • key (Required): The key from step 1.

    Status Codes:

    • 800: QR code expired.
    • 801: Waiting for scan.
    • 802: Waiting for confirmation.
    • 803: Authorized and logged in (returns cookies).
    • 502: If encountered during scan, add &noCookie=true to the request.

    Example (Step 2): /login/qr/create?key=xxx

  5. Install and run NeteaseCloudMusicApiEnhanced locally

    main

    To run the API service locally, ensure you have Node.js 22 or higher installed. It is recommended to use pnpm for dependency management.

    Installation

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

    Starting the service

    By default, the service runs on port 3000.

    Default port (3000):

    node app.js

    Custom port (e.g., 4000):

    On Mac/Linux:

    PORT=4000 node app.js

    On Windows:

    set PORT=4000 && node app.js
    git clone https://github.com/neteasecloudmusicapienhanced/api-enhanced.git
cd api-enhanced
pnpm i

# Start default
node app.js

# Start custom port (Mac/Linux)
PORT=4000 node app.js

  7. Deploy to Vercel

    main

    The project includes Vercel configuration files for direct deployment.

    Important Notes:

    • When accessing Vercel-deployed interfaces, you must include a realIP parameter (e.g., /song/url?id=1969519579&realIP=116.25.146.177).
    • To use random Chinese IPs, add the query parameter randomCNIP=true (e.g., /song/url?id=1969519579&randomCNIP=true).
    • If access is blocked, binding a domain with a domestic Chinese ICP filing may resolve the issue.

  9. Deploy using Docker

    main

    You can deploy the API using Docker without manually installing Node.js or dependencies.

    Pull and Run

    To pull the latest image and run it on port 3000:

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

    Handling Proxy Environment Variables

    When running in Docker, the underlying request library checks several proxy environment variables. If these point to invalid proxies, requests will fail. You can override these by passing an empty value or by providing a proxy parameter in your API queries.

    To explicitly clear proxy environment variables in Docker:

    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

    Build your own Docker image

    git clone https://github.com/NeteaseCloudMusicApiEnhanced/api-enhanced && cd api-enhanced
sudo docker build . -t ncm-api
sudo docker run -d -p 3000:3000 ncm-api

    Update the image

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

  11. Upload to Cloud Drive

    main

    Cloud Drive uploading supports two modes:

    1. Backend Proxy Mode (Default)

    Files are forwarded through the server to cloud storage.

    • Limitation: Vercel Serverless Functions are limited to a 4.5MB request body. Self-hosted servers must be configured to allow larger request bodies.
    • Endpoint: /cloud
    • Requirement: Use Content-Type: multipart/form-data with the file in a field named songFile.

    2. Client-Side Direct Upload (Recommended for Vercel)

    Files are uploaded directly from the client to cloud storage, bypassing server body limits. This is ideal for large files and platforms like Vercel or Netlify.

    Direct Upload Workflow:

    1. Client calculates the file's MD5.
    2. Call /cloud/upload/token to get an upload credential.
    3. If needUpload is true, perform a PUT request of the file to the provided uploadUrl.
    4. Call /cloud/upload/complete to finalize the import.

    Direct Upload Endpoints:

    • Get Upload Token: /cloud/upload/token (Required: cookie in request body, md5, fileSize, filename).
    • Complete Upload/Import: /cloud/upload/complete (Required: cookie in request body, songId, resourceId, md5, filename. Optional: song, artist, album).
    // Response from /cloud/upload/token
{
  "code": 200,
  "data": {
    "needUpload": true,
    "songId": "...",
    "uploadToken": "...",
    "uploadUrl": "...",
    "resourceId": "..."
  }
}

  12. Deploy to Vercel or Tencent Cloud Serverless

    main

    Vercel

    1. Fork this repository.
    2. Create a new project in the Vercel dashboard and import your fork.
    3. Click Deploy.

    Tencent Cloud Serverless

    1. Fork this repository.
    2. Create a new Web application in the Tencent Cloud Serverless console using the Express framework.
    3. Select your forked repository as the code source.
    4. Set the startup file to the following script:
    #!/bin/bash
export PORT=9000
/var/lang/node16/bin/node app.js
    1. Complete the deployment and access the API via the provided API Gateway URL.
    #!/bin/bash
export PORT=9000
/var/lang/node16/bin/node app.js