gcui-art/suno-api: an unofficial HTTP wrapper around Suno's web app

The gap gcui-art/suno-api fills, and who ends up using it

Suno is a music generation service whose official API, as the README states plainly, is "not yet available". That leaves anyone building an agent, a Discord bot or a batch pipeline with two options: drive the web UI by hand, or reverse the browser traffic. This project takes the second route and packages it as a Next.js application that answers HTTP requests.

The intended audience is narrow but real. The README describes integrating the output into "agents like GPTs" and Coze, and the feature list includes compatibility with the format of OpenAI's /v1/chat/completions API. If you are wiring a tool into an LLM platform that expects an OpenAI-shaped endpoint, that compatibility is the actual selling point, not the music generation itself. Individual hobbyists who just want to generate songs are better served by the Suno website directly; the overhead of a cookie, a CAPTCHA account and a deployment only pays off when something automated is calling it.

The project is published under LGPL-3.0-or-later and carries version 1.1.0 in package.json. The last push to the repository was on 2026-03-06.

How the CAPTCHA solving and cookie flow actually work

There is no hidden API key here. The service authenticates as your Suno account by replaying the Cookie header you copy out of your own browser session, and it solves the hCaptcha challenges Suno throws up using a real Playwright browser instance plus the paid 2Captcha service. The README is explicit that the implementation "uses the paid 2Captcha service ... and does not use any already made closed-source paid Suno API implementations".

The dependency list confirms the machinery: @2captcha/captcha-solver, @playwright/browser-chromium, rebrowser-playwright-core and ghost-cursor-playwright are all direct dependencies. rebrowser-patches is referenced in the README as the mechanism for making the automated browser less detectable. That is the whole architecture: an HTTP server that, on request, launches or reuses a headless browser to clear the challenge, then forwards the generation call to Suno with your cookie attached.

Two configuration details reveal how fragile this is. BROWSER_GHOST_CURSOR is documented as simulating smooth mouse movements, but the README undercuts its own feature: "it doesn't seem to make any difference in the rate of CAPTCHAs, so you can set it to false. Retained for future testing." A knob that the maintainer says does nothing is a fair signal that detection avoidance here is empirical rather than solved. Separately, the README recommends macOS because "macOS systems usually get fewer CAPTCHAs than Linux and Windows". Your host operating system changes your operating cost. That is an unusual constraint for a server-side tool.

Installing gcui-art/suno-api locally and sending a first request

The README gives three deployment paths: Vercel via the clone button, a local Node run, and Docker or Docker Compose. The local path is the one you can inspect. Clone the repository and install dependencies with npm as the README shows:

git clone https://github.com/gcui-art/suno-api.git
cd suno-api
npm install

Before the server will do anything useful you need a Suno cookie and a 2Captcha key. The README walks through the cookie extraction: open suno.com/create, open developer tools, go to the Network tab, refresh, find the request containing ?__clerk_api_version, and copy the Cookie header value. The 2Captcha key comes from a funded account at 2captcha.com. The repository ships an .env.example that lists every variable the app reads:

SUNO_COOKIE=<…>
TWOCAPTCHA_KEY=<…>
BROWSER=chromium
BROWSER_GHOST_CURSOR=false
BROWSER_LOCALE=en
BROWSER_HEADLESS=true

BROWSER accepts chromium or firefox, and the README recommends chromium. BROWSER_LOCALE should be en or ru because those languages have the most workers on 2Captcha. BROWSER_HEADLESS should be true for a server. Copy this into .env and fill in the first two values.

If you prefer containers, the repository includes a compose file that builds the image, mounts ./public, reads .env and publishes port 3000:

docker compose build && docker compose up

The README warns that GPU acceleration is disabled in Docker and suggests deploying locally if you have a slow CPU. Once the server is up, the demo deployment and the /docs route on the project's own site are the reference for request shapes; the README points to https://suno.gcui.ai/docs for the API documentation rather than inlining the schema.

The cookie is the failure mode you will hit first

Everything in this design hangs off SUNO_COOKIE. It is a session credential copied out of a browser, not a long-lived API token, and the README offers no rotation, refresh or expiry handling for it. The feature list claims the project will "automatically keep the account active", but the README does not document what happens when the cookie is rejected, whether the server surfaces a distinct error, or how you would detect the failure before your agent starts returning garbage. That silence is the biggest operational risk in the project.

There is a second cost that is easy to underestimate. CAPTCHA solving is paid, per solve, through 2Captcha, and the README does not quote a price. So the true cost of running this is your hosting plus a metered third-party service whose volume depends on how aggressively Suno challenges your traffic, which in turn depends on your OS and locale. There is no way to compute a per-song cost from the README alone; you would have to measure your own challenge rate.

Finally, this is a wrapper around a private web interface. Suno can change that interface at any time, and nothing in the repository contract promises otherwise. If your product depends on generation working every hour of every day, this is the wrong layer to build on.

How it differs from calling Suno through an official or hosted API

The obvious alternative is a hosted, closed-source Suno API service of the kind the README says it deliberately avoids using. The difference is not just licensing, it is where the failure lands. A hosted provider absorbs the cookie churn, the CAPTCHA spend and the interface changes, and charges you a markup for that. gcui-art/suno-api pushes all three onto you: you supply the account, you fund the CAPTCHA solver, and you redeploy when Suno's front end shifts. In exchange you keep the code, can read exactly what it sends, and pay 2Captcha directly instead of a reseller.

A second alternative is to wait for, or use, an official API if one becomes available. The README's framing is that the official API is not yet available, which is the entire reason the project exists. If your timeline is measured in months rather than days, building against a private interface that can break without notice is a poor trade against waiting for a supported endpoint.

A third option, worth naming because it is genuinely different in approach: drive the Suno web app yourself with Playwright and no HTTP layer at all. You would skip the server, the Vercel deployment and the OpenAI-compatible shim, and you would lose the ability to hand a URL to an agent platform. Whether that matters depends entirely on whether your consumer speaks HTTP or is your own script.

Licence position and what upgrades cost you

The repository is licensed LGPL-3.0-or-later, and package.json agrees. That is not the permissive licence the README's feature list implies when it says "permissive open-source license, allowing you to freely integrate and modify". LGPL is a copyleft licence with specific obligations around modified library code and relinking, and the README does not discuss any of them. If you plan to embed this in a distributed product, read the LICENSE file in the repository rather than the feature bullet, and get your own legal read; nothing here is legal advice.

The upgrade story is thin. There are no retrieved releases, so version 1.1.0 in package.json is the only version marker available, and the README's upgrade guidance amounts to "We update quickly, please star." There is no changelog, no migration notes and no documented rollback path. In practice your upgrade cost is the cost of re-verifying that the endpoints still match Suno's current front end, plus re-checking your .env against .env.example in case a variable was added. The last push was on 2026-03-06, so treat the code as it stands rather than assuming fixes are landing.

Editorial conclusion

Adopt gcui-art/suno-api if you need programmatic Suno generation today and accept that it drives the web app rather than an official endpoint: budget for 2Captcha credit, expect to re-paste SUNO_COOKIE when the session dies, and prefer a macOS host if CAPTCHA volume matters. Do not adopt it if you need a supported SLA, a stable contract, or a licence you can embed in closed-source code without reviewing LGPL-3.0 obligations. Before committing, verify that the API schema in src/ still matches the endpoints your agent calls, and confirm the current 2Captcha pricing at 2captcha.com/pay, since the README does not state a cost per solve.

Frequently asked questions

Official sources

1. gcui-art/suno-api on GitHub
2. Issues
3. License: LGPL-3.0
4. Project website
5. README