Documentation Index
Fetch the complete documentation index at: https://mintlify.com/gcui-art/suno-api/llms.txt
Use this file to discover all available pages before exploring further.
Environment variables
All deployment options share the same set of environment variables. Configure these before starting the server.
| Variable | Required | Description |
|---|
SUNO_COOKIE | Yes | Full Cookie header string copied from your browser’s DevTools while on suno.com |
TWOCAPTCHA_KEY | Yes | API key from your 2Captcha account |
BROWSER | Yes | Browser to use for CAPTCHA solving. chromium (recommended) or firefox |
BROWSER_GHOST_CURSOR | No | Simulate smooth mouse movements with ghost-cursor-playwright. Set to false — it does not reduce CAPTCHA frequency |
BROWSER_LOCALE | No | Browser locale sent to 2Captcha workers. en or ru recommended for fastest solving |
BROWSER_HEADLESS | No | Run the browser without a visible window. Set to true on servers |
BROWSER_DISABLE_GPU | No | Disable GPU acceleration. Set automatically to true inside Docker |
Vercel
Docker Compose
Run locally
Vercel is the fastest way to get a public HTTPS endpoint without managing infrastructure.Vercel serverless functions have a 10-second execution timeout on the Hobby plan. Suno generation requests often take longer than that. If you hit timeouts frequently, use the Docker or local deployment instead, or upgrade to a Vercel Pro plan (60-second limit).
Click Deploy
Or open the URL directly:https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fgcui-art%2Fsuno-api&env=SUNO_COOKIE,TWOCAPTCHA_KEY,BROWSER,BROWSER_GHOST_CURSOR,BROWSER_LOCALE,BROWSER_HEADLESS&project-name=suno-api&repository-name=suno-api
Set environment variables
Vercel will prompt you to fill in the environment variables during the clone flow. Set at minimum:SUNO_COOKIE=<your cookie>
TWOCAPTCHA_KEY=<your 2captcha key>
BROWSER=chromium
BROWSER_GHOST_CURSOR=false
BROWSER_LOCALE=en
BROWSER_HEADLESS=true
Wait for the deployment to finish
Vercel will fork the repository to your GitHub account, build the Next.js app, and deploy it. This usually takes 2–4 minutes.
Test the deployment
Replace <your-vercel-domain> with the domain Vercel assigned to your project:curl https://<your-vercel-domain>/api/get_limit
{
"credits_left": 50,
"period": "day",
"monthly_limit": 50,
"monthly_usage": 50
}
Docker Compose runs Suno API in a container. The image installs Playwright’s Chromium browser and all system dependencies automatically.GPU acceleration is disabled inside the Docker container (BROWSER_DISABLE_GPU=true is set in the Dockerfile). If you have a slow CPU, generation may be sluggish. In that case, prefer the local deployment.
Create your .env file
The Compose file reads variables from .env at runtime and also passes SUNO_COOKIE as a build argument.cp .env.example .env
# Edit .env and fill in SUNO_COOKIE, TWOCAPTCHA_KEY, and the BROWSER_* variables
.env format:SUNO_COOKIE=<your cookie>
TWOCAPTCHA_KEY=<your 2captcha key>
BROWSER=chromium
BROWSER_GHOST_CURSOR=false
BROWSER_LOCALE=en
BROWSER_HEADLESS=true
Build and start the container
docker compose build && docker compose up
docker-compose.yml used:version: '3'
services:
suno-api:
build:
context: .
args:
SUNO_COOKIE: ${SUNO_COOKIE}
volumes:
- ./public:/app/public
ports:
- "3000:3000"
env_file: ".env"
3000.Verify the server
curl http://localhost:3000/api/get_limit
The ./public directory is mounted as a volume so that CAPTCHA instruction images (used by the 2Captcha solver) are accessible inside the container without requiring a rebuild.
Running locally is the simplest option for development and is recommended for macOS users.macOS systems receive significantly fewer hCaptcha challenges than Linux or Windows. This is because macOS has low representation in the web-scraping industry, so Suno’s fraud-detection model is less suspicious of it. Fewer CAPTCHAs means lower 2Captcha costs and faster responses.
Clone the repository
git clone https://github.com/gcui-art/suno-api.git
cd suno-api
Install dependencies
This installs all Node packages including rebrowser-playwright-core and the @playwright/browser-chromium browser binary. Create and configure .env
Edit .env:SUNO_COOKIE=<your cookie>
TWOCAPTCHA_KEY=<your 2captcha key>
BROWSER=chromium
BROWSER_GHOST_CURSOR=false
BROWSER_LOCALE=en
BROWSER_HEADLESS=true
Start the server
The Next.js dev server starts on http://localhost:3000 with hot-reload enabled. Verify the server
curl http://localhost:3000/api/get_limit
{
"credits_left": 50,
"period": "day",
"monthly_limit": 50,
"monthly_usage": 50
}
