sunoapi.comConsole
SUNOAPI / GET STARTED

Suno API documentation: your first song

Create an API key, check your credits, and turn a musical brief into an asynchronous song task. These examples use the API belonging to this deployment.

Choose the correct API environment#

During preview, use the base URL below with an API key created in this site’s console. The preview and the existing public API have separate accounts and balances. Do not use a legacy key or change the host to api.sunoapi.com until the new service has launched.

Example
export SUNO_API_BASE="https://sunoapi.com/api/v1"
export SUNO_API_KEY="your_api_key"

1. Create a key and check your balance#

Sign in, open API keys, and create a key. Keep it on your server. New accounts start with zero credits; one generation request reserves 20 credits. Balance and task lookups do not consume generation credits.

Example
curl "$SUNO_API_BASE/get-credits" \
  --header "Authorization: Bearer $SUNO_API_KEY"

# HTTP 200 (illustrative funded balance)
# {"credits":0,"extra_credits":1000}
# Available credits = credits + extra_credits

2. Submit a description#

Create and save a UUID before sending the request. It is both the Idempotency-Key and task_id. Description mode composes lyrics and arrangement from a brief of at most 400 characters.

Example
export SUNO_REQUEST_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
# Save SUNO_REQUEST_ID before sending.
curl --request POST "$SUNO_API_BASE/sonic/create" \
  --header "Authorization: Bearer $SUNO_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $SUNO_REQUEST_ID" \
  --data '{"custom_mode":false,"mv":"sonic-v6-mini","gpt_description_prompt":"Warm acoustic folk, intimate vocals, a song about finding home","make_instrumental":false}'

3. Keep the task ID#

A pending response uses HTTP 202. The following is a representative response, not a live generation. A submitted status means the service has associated a provider job with your task; it does not mean audio is ready.

Example
{
  "task_id": "a4ef5803-48f7-42cc-9697-cc1b1be9d042",
  "status": "submitted",
  "code": 102,
  "type": "not_ready",
  "message": "Song generation is pending."
}

4. Retrieve the audio#

Use the same account’s key to look up the saved UUID. Wait five seconds between pending responses and stop at a deadline. On HTTP 200, check for type: failed before reading data[].audio_url. A request can return multiple tracks; keep each track associated with the original task.

Example
curl "$SUNO_API_BASE/sonic/task/$SUNO_REQUEST_ID" \
  --header "Authorization: Bearer $SUNO_API_KEY"

# Completed response shape (placeholder audio URL):
# {"data":[{"id":"track-id","title":"Finding Home","audio_url":"https://audio.example/track.mp3"}]}

Recover instead of generating again#

If the create response is lost, query your saved task ID. Reusing the UUID with the same payload does not reserve credits or submit a provider job twice. A different payload with the same UUID returns 409. An unknown or reserved task needs confirmation; retain the reservation and do not invent a new UUID to retry.

Try the workbench, then move to your backend#

The homepage workbench builds the same public request and can generate with your account credits. Its key stays in page memory and is not saved in browser storage; only the latest task ID is saved in the tab’s session storage. Keep production secrets on your backend, outside browser bundles, mobile binaries, repositories and analytics.

Your SunoAPI account

Manage your API keys, account access, and generation credits through sunoapi.com.

Open SunoAPI API keys
Try the request workbench Next: Generate a song