Authentication

Updated 2026-09-18 · Suno-API team

Every request to the Suno-API is authenticated with an API key. This page covers how to create a key, how to send it, what the error responses mean, and how to keep the key safe.

API keys

An API key is a bearer token tied to your account. It carries your balance, so anything that has the key can spend it. Keys are created per account and are shown only once — copy a new key immediately and store it somewhere safe.

Creating a key

1. Register at https://www.suno-api.io — an email address is enough, no phone number.
2. Open the console and go to token management.
3. Create a new key and copy it.

Keys look like sk-…. If you lose a key you cannot recover it; create a new one and delete the old one.

Using a key

Send the key in the Authorization header on every request:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Example

Waiting time and timeouts. The example below calls a generation endpoint (POST /api/music/create), which is synchronous: the order is only accepted once the response arrives, and there is no intermediate response while the service schedules an account and runs the required upstream safety check. Measured on production: most requests return in 1-3 seconds, about 10% take longer than 30 seconds, and the longest observed wait is about 230 seconds. Set your client timeout to 300 seconds or more. A timeout or dropped connection does not mean the song was not generated - the order may already be accepted and generating. Do not retry immediately (that creates a second order and charges again); check GET /api/music/songs first. See "Waiting time and timeouts" in the API overview.

curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{"description": "a calm piano piece for a cafe"}'

Authentication errors

401 Unauthorized

The header is missing, malformed, or the key does not exist.

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

Check that the header reads exactly Bearer <key> — with a space after Bearer — and that you have not copied a trailing newline into the key.

403 Forbidden

The key is valid but is not allowed to perform this request, most often because the account balance is exhausted.

Top up the account, then retry the same request.

Security practices

Keep the key out of client-side code

Never ship a key inside a web page, a mobile app or a desktop binary. Anyone who can open developer tools can read it and spend your balance. Call the API from your own server and expose your own endpoint to your users.

Use environment variables

# ~/.bashrc or ~/.zshrc
export SUNO_API_KEY="sk-your-key-here"

# in code
curl -H "Authorization: Bearer $SUNO_API_KEY" ...

# python
import os
api_key = os.environ["SUNO_API_KEY"]

# .env file — make sure it is listed in .gitignore
SUNO_API_KEY=sk-your-key-here

Rotate keys when needed

If a key may have leaked, create a replacement and delete the old one. Rotating is cheap; an exposed key is not.

Rate limits

Requests are rate limited per key. When you exceed the limit the API returns 429 Too Many Requests:

{
  "error": {
    "message": "Rate limit exceeded, please retry later",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

Retry with exponential backoff rather than in a tight loop:

import time

delay = 1.0
for attempt in range(5):
    response = call_api()
    if response.status_code != 429:
        break
    time.sleep(delay)
    delay *= 2

FAQ

What format does an API key have?

It starts with sk- followed by a random string. Treat the whole value as one token.

Can I call the API directly from a browser?

Technically yes, but do not do it in production. The key would be visible to every visitor. Proxy the request through your own backend instead.

How do I check whether a key is still valid?

Make any authenticated request. A 200 means the key works; 401 means it is invalid or deleted.

I lost my key — what now?

Keys cannot be recovered. Create a new one in the console and delete the old entry.

How many keys can one account have?

Several. Use one key per application or environment so you can revoke them independently.

Do keys expire?

Keys stay valid until you delete them or the account is closed. Rotate them periodically as good practice.

How do I monitor usage?

Balance and usage are visible in the console. Each generation costs ¥0.6 and returns two tracks; failed generations are refunded automatically.

Related pages

• Quick start guide
• Supported models