Skip to main content
1

Obtain your Suno cookie

Suno API authenticates with Suno using your browser session cookie.
  1. Open suno.com/create in your browser.
  2. Press F12 (or right-click → Inspect) to open Developer Tools.
  3. Go to the Network tab and refresh the page.
  4. In the filter box, type __clerk_api_version to find the Clerk authentication request.
  5. Click on that request, then open the Headers tab.
  6. Scroll to the Request Headers section, find Cookie, and copy the entire value.
The cookie contains your session credentials. Treat it like a password — do not commit it to version control or share it publicly.
2

Get a 2Captcha API key

Suno requires an hCaptcha challenge on every generation. Suno API solves it automatically using 2Captcha.
  1. Register a new 2Captcha account.
  2. Top up your balance (a small amount covers many requests).
  3. Copy your API key from the recognition page.
3

Clone the repository and install dependencies

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

Create your .env file

Copy the example file and fill in your values:
cp .env.example .env
Edit .env:
SUNO_COOKIE=<paste the full cookie string you copied in step 1>
TWOCAPTCHA_KEY=<your 2Captcha API key>
BROWSER=chromium
BROWSER_GHOST_CURSOR=false
BROWSER_LOCALE=en
BROWSER_HEADLESS=true
Use BROWSER_LOCALE=en or BROWSER_LOCALE=ru — these two locales have the highest worker count on 2Captcha, which means faster CAPTCHA solving.
5

Start the development server

npm run dev
The server starts on http://localhost:3000.
6

Verify the server is running

Call the quota endpoint to confirm your cookie is valid and the server is healthy:
curl http://localhost:3000/api/get_limit
Expected response:
{
  "credits_left": 50,
  "period": "day",
  "monthly_limit": 50,
  "monthly_usage": 50
}
If you see this response, the server is connected to Suno and your session is active.
7

Generate your first song

Send a prompt to /api/generate. The endpoint returns immediately with two clip objects (Suno always generates two variations). The status field will be "submitted" or "queued" — audio is not ready yet.
curl -X POST http://localhost:3000/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A popular heavy metal song about war, sung by a deep-voiced male singer, slowly and melodiously. The lyrics depict the sorrow of people after the war.",
    "make_instrumental": false,
    "wait_audio": false
  }'
8

Poll for completion

Take the id values from the generate response and poll /api/get until status becomes "streaming" or "complete". At that point audio_url contains a playable link.
# Replace IDs with the actual values from the generate response
curl "http://localhost:3000/api/get?ids=<id1>,<id2>"
When status is "streaming", the file is being written but is already playable. When it is "complete", the full audio file is available.

​
Next steps

Deployment

Deploy to Vercel, Docker Compose, or run locally in production

API Reference

Full endpoint documentation including custom mode, stems, and lyrics

Build docs developers (and LLMs) love

Get started for freeTalk to us