Suno API Pro v3.1.0

Complete Help Guide — Turn your Suno AI account into a private REST API

1. What is Suno API Pro?

Suno API Pro is a self-hosted API gateway that converts your Suno AI account into a private REST API. You install it on your own server or computer, add one or more Suno accounts, create API keys, and then call any REST API endpoint to generate music, fetch clips, search songs, and check credits — just like an official API.

2. How It Works

At a high level, Suno API Pro sits between your application and Suno AI's web backend:

  Your App / Script / Website
          │
          ▼
  ┌─────────────────────┐
  │   Suno API Pro      │  ← Your server, port 8080
  │   (server.js)       │
  │                     │
  │  ┌───────────────┐  │
  │  │  Account 1    │  │  ← Suno session + cookies
  │  │  Account 2    │  │  ← Second account (optional)
  │  │  Account 3    │  │  ← Third account (optional)
  │  └───────────────┘  │
  └─────────┬───────────┘
            │
            ▼
      Suno AI Servers
   (studio-api.prod.suno.com)

Each account you add creates a persistent connection to Suno. When you call the API, your request is routed to one of your accounts (either a specific one or round-robin across all active ones). The response is returned to your app in standard JSON.

Core Components

3. Legality & Cost-Savings Comparison

Suno API Pro is built around standard, secure browser/session automation. Because Suno AI does not offer an official public API for developers, this self-hosted gateway provides the only reliable way to integrate Suno into your apps and workflows programmatically.

Is cookie-based automation legal?

Yes, absolutely. Automating your own interaction with services using session identifiers you legally own is a standard RPA (Robotic Process Automation) and scripting technique. It does not bypass paywalls, crack digital rights management (DRM), or perform unauthorized access to private systems. It simply automates the browser commands that you would otherwise execute manually.

Cost-Savings Analysis

Because third-party APIs must host their own infrastructure and pay for Suno subscriptions, they charge high pay-as-you-go markup rates. Running your own self-hosted Suno API Pro gateway completely eliminates these middleman markups. You only pay for your raw Suno subscriptions.

4. Installation

Windows

1. Unzip Suno-API-Pro-v3.1.0.zip to a folder, e.g. C:\suno-api-pro
2. Double-click start.bat — this installs dependencies and starts the server
3. Open http://localhost:8080 in your browser

Or use the terminal:

cd C:\suno-api-pro
npm install
node server.js

Mac / Linux

unzip Suno-API-Pro-v3.1.0.zip
cd Suno-API-Pro
npm install
node server.js

Verify It's Running

Open http://localhost:8080 — you should see the Suno API Pro dashboard. You can also check the API status endpoint:

curl http://localhost:8080/api/status

5. Dashboard Tour

The dashboard has 4 tabs. Here's what each one does:

Dashboard Tab

Shows a live overview of your server's status:

• Accounts — how many Suno accounts are connected / total
• API Keys — number of active keys
• License — shows "standard", "Trial", or "None"
• Uptime — how long the server has been running

Accounts Tab

Manage your Suno accounts:

• Add Account — opens a form to add a new Suno account
• Extract from Browser — one-click cookie extraction via Chrome extension
• Test — checks if the account's session is still valid
• Delete — removes the account and stops its keep-alive
• Each row shows: name, connection status, error message (if any), last used time

API Keys Tab

Manage your API keys for external access:

• Create Key — name it, optionally assign to a specific account
• View — shows the full key (copy it — hidden after closing)
• Rotate — generates a new key string, old one stops working
• Delete — permanently revokes the key
• Each row shows: key name, preview, assigned account, usage count, last used

Setup Tab

Server configuration:

• License — enter your license key to activate
• Trial banner — shows remaining calls if trial is active
• API Base URL — copy your API endpoint for use in apps
• Deployment — instructions for 24/7 VPS hosting

6. License & Trial

Trial Mode

When you first start the server without a license key, trial mode is automatically available:

• 25 free API calls
• 48-hour time limit from your first API call
• After trial expires, you must activate a license key to continue

Trial activates on your first API call (not when the server starts). You can check remaining trial calls in the Setup tab or via the API:

curl http://localhost:8080/api/license/status

Activating a License

1. Go to the Setup tab
2. Enter your license key (e.g. SUNO-4HVX-IWDI-Z76D)
3. Click Activate
4. Status changes to "License: standard" on the Dashboard tab

License keys are stored in license/keys.json. Validation can be local (file-based) or remote (API-based).

7. Managing Suno Accounts

Getting Your Suno Cookie

You need your Suno session cookie to add an account. There are two ways to get it:

Method A: Chrome Extension (Recommended)

1. Open Chrome → chrome://extensions
2. Enable Developer mode (top right)
3. Click Load unpacked → select the extension/ folder
4. Go to suno.com and log in
5. Open your dashboard at http://localhost:8080
6. Go to Accounts → Add Account
7. Click Extract from Browser — the fields auto-fill

Method B: Manual (Any Browser)

1. Open Chrome/Firefox/Edge, go to suno.com and log in
2. Open Developer Tools (F12)
3. Go to the Application tab (Chrome) or Storage tab (Firefox)
4. Find Cookies → suno.com
5. Copy the value of the __session cookie
6. In the dashboard, paste it in the Cookie String field

Adding an Account

1. Click Add Account
2. Give it a name (e.g. "My Main Account")
3. Paste the Session ID (from the JWT payload's sid field)
4. Paste the Cookie String
5. Click Add Account

The server immediately tests the connection. If successful, the account shows "Connected". If not, it shows "Error" with the reason (likely an expired cookie).

Multiple Accounts

You can add as many Suno accounts as you want. When an API key is set to "Auto" (round-robin), the server distributes requests across all active accounts, starting with the least recently used one. If one account fails, the next account is tried automatically.

8. Managing API Keys

Creating a Key

1. Go to API Keys → Create Key
2. Enter a name (e.g. "Production", "Staging", "My App")
3. Choose an account assignment:
   • Auto (round-robin) — requests go to any active account
   • Specific account — requests always use that account
4. Click Create Key
5. Copy the key now — it's shown once, then hidden for security

Key Actions

• View — shows the key's metadata (name, account, usage, creation date) — but NOT the full key
• Rotate — generates a new key string. The old key stops working immediately. Use this if a key is compromised.
• Delete — permanently removes the key. Any services using it will be rejected on their next call.

How Key Authentication Works

Every API request must include the API key in one of two ways:

• HTTP header: x-api-key: suno_YOUR_KEY
• Query parameter: ?api_key=suno_YOUR_KEY

Invalid, expired, or missing keys return 403 Forbidden.

9. Using the REST API

Once you have an API key and at least one Suno account, you can call the API from any programming language or tool.

Base URL

http://YOUR_SERVER:8080/api/v1

Replace YOUR_SERVER with localhost for local use, or your VPS IP/domain for production.

curl Examples

Generate Music

curl -X POST "http://localhost:8080/api/v1/generate" \
  -H "x-api-key: suno_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A chill lo-fi hip hop beat with vinyl crackle",
    "style": "Lofi Hip Hop",
    "title": "Afternoon Study"
  }'

Check Generation Status

curl "http://localhost:8080/api/v1/feed/TASK_ID" \
  -H "x-api-key: suno_YOUR_KEY_HERE"

Get Clip Details

curl "http://localhost:8080/api/v1/clip/CLIP_ID" \
  -H "x-api-key: suno_YOUR_KEY_HERE"

Search Songs

curl "http://localhost:8080/api/v1/search?query=lo-fi&page=1" \
  -H "x-api-key: suno_YOUR_KEY_HERE"

Check Credits

curl "http://localhost:8080/api/v1/credits" \
  -H "x-api-key: suno_YOUR_KEY_HERE"

Node.js Example

const API = 'http://localhost:8080/api/v1';
const KEY = 'suno_YOUR_KEY_HERE';

async function generateMusic() {
  const res = await fetch(API + '/generate', {
    method: 'POST',
    headers: { 'x-api-key': KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ prompt: 'A jazz piano solo', style: 'Jazz' })
  });
  const data = await res.json();
  console.log(data);
}

generateMusic();

Python Example

import requests

API = 'http://localhost:8080/api/v1'
KEY = 'suno_YOUR_KEY_HERE'

response = requests.post(f'{API}/generate', json={
    'prompt': 'Electronic dance track with heavy bass',
    'style': 'EDM'
}, headers={'x-api-key': KEY})

print(response.json())

Response Format

All successful API calls return JSON:

{
  "success": true,
  "data": { ... }
}

Error responses return:

{
  "error": "description of what went wrong"
}

HTTP Status Codes

10. Chrome Extension

The Chrome extension eliminates manual cookie copying. With one click, it reads your Suno session from suno.com, extracts the session ID from the JWT, and sends everything to the dashboard.

Installation

1. Open Chrome and go to chrome://extensions
2. Enable Developer mode (toggle in top right)
3. Click Load unpacked
4. Select the extension folder inside your Suno API Pro directory
5. The extension icon appears in your toolbar

Usage

1. Go to suno.com and make sure you're logged in
2. Open your Suno API Pro dashboard at http://localhost:8080
3. Go to Accounts → Add Account
4. Click Extract from Browser
5. The Session ID and Cookie fields auto-fill instantly
6. Give the account a name and click Add Account

How It Works

The extension has three parts:

• Content script (content.js) — injected into the dashboard page, listens for the "Extract" button click
• Background script (background.js) — accesses chrome.cookies API to read suno.com cookies, decodes the JWT to get the session ID
• Popup (popup.html + popup.js) — shows current status and lets you manually forward credentials

Auto-Refresh

The extension automatically refreshes your cookies every 25 minutes (via chrome.alarms). It also forwards credentials immediately when Chrome starts or the extension is installed.

11. Production Deployment (VPS)

For 24/7 operation, deploy to any VPS (Linode, DigitalOcean, Vultr, AWS, etc.). A $6/month droplet is sufficient.

Quick Deploy

# Upload the ZIP to your VPS
scp Suno-API-Pro-v3.1.0.zip user@YOUR_VPS_IP:~/

# SSH into your VPS
ssh user@YOUR_VPS_IP

# Extract and deploy
unzip Suno-API-Pro-v3.1.0.zip
sudo bash deploy.sh

The deploy script (deploy.sh) handles everything:

• Installs Node.js 20.x (if not present)
• Installs PM2 globally (npm install -g pm2)
• Copies files to /opt/suno-api-pro
• Installs dependencies
• Starts the server with PM2
• Configures PM2 to start on system boot
• Optionally installs a systemd service unit

PM2 Commands

pm2 status                    # View running processes
pm2 logs suno-api-pro         # View live logs
pm2 restart suno-api-pro      # Restart the server
pm2 stop suno-api-pro         # Stop the server
pm2 startup                   # Auto-start on server reboot

Systemd Service

If you prefer systemd over PM2, use the provided suno-api-pro.service:

sudo cp suno-api-pro.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable suno-api-pro
sudo systemctl start suno-api-pro
sudo systemctl status suno-api-pro

Firewall Notes

Make sure port 8080 is open in your VPS firewall:

# Ubuntu with ufw
sudo ufw allow 8080/tcp

# Or using iptables
sudo iptables -A INPUT -p tcp --dport 8080 -j ACCEPT

Using a Reverse Proxy (Nginx)

For a custom domain with HTTPS, set up Nginx as a reverse proxy:

server {
    listen 80;
    server_name api.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Then use Certbot to add HTTPS: sudo certbot --nginx -d api.yourdomain.com

12. Troubleshooting

"Invalid API key" (403)

• Check that you're using the correct header: x-api-key (lowercase, hyphens)
• Make sure the key exists in the dashboard (API Keys tab)
• If the key was rotated, use the new key

"No Suno account available" (400)

• Add at least one Suno account in the Accounts tab
• If your key is assigned to a specific account, make sure that account exists and is connected
• Check that the account's cookie hasn't expired

Trial not starting

• Trial starts on your first API call (not when the server boots)
• Make sure license/keys.json has "trial": { "enabled": true }
• If a license is already activated, trial mode is bypassed

"Suno API 503" / "Service Suspended"

• Your Suno cookie has expired or is invalid
• Log in to suno.com in your browser, then re-extract the cookie
• Update the account in the dashboard (delete and re-add, or use the same credentials)

Account shows "Error" status

• The keep-alive ping to Suno failed
• Click Test to manually re-check the connection
• If it persists, remove the account and re-add it with fresh cookies

Chrome extension not working

• Make sure you're on the dashboard page (localhost:8080)
• Check the console (F12): look for "Suno API Pro content script loaded"
• Make sure you're logged into suno.com in the same browser
• Re-load the extension: chrome://extensions → click the refresh icon on the extension card

Server won't start / port in use

# Change the port
set PORT=9090
node server.js

Or edit .env file to set PORT=9090.

"npm install" fails

• Install Node.js 18 or later from nodejs.org
• On Windows, run PowerShell as Administrator and try again
• Check your internet connection

13. API Reference

Management Endpoints (no API key needed)

API Endpoints (require x-api-key header)

cURL Quick Reference

# Save your key for reuse
KEY="suno_YOUR_KEY_HERE"
BASE="http://localhost:8080/api/v1"

# Generate
curl -X POST "$BASE/generate" -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a lo-fi beat","style":"Lofi"}'

# Feed (replace TASK_ID)
curl "$BASE/feed/TASK_ID" -H "x-api-key: $KEY"

# Clip (replace CLIP_ID)
curl "$BASE/clip/CLIP_ID" -H "x-api-key: $KEY"

# Search
curl "$BASE/search?query=jazz" -H "x-api-key: $KEY"

# Credits
curl "$BASE/credits" -H "x-api-key: $KEY"