Skip to main content
POST
/
api
/
v1
/
generate
/
sounds
Generate Sounds
curl --request POST \
  --url https://api.sunoapi.org/api/v1/generate/sounds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "A soft rain ambience with distant thunder and gentle wind",
  "model": "V5",
  "soundLoop": false,
  "soundTempo": 120,
  "soundKey": "Any",
  "grabLyrics": false,
  "callBackUrl": "https://api.example.com/callback"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "a1b2****c3d4"
  }
}
Used for creating a sound generation task (Sounds Task). It supports settings for looping, tempo (BPM), pitch (Key), as well as lyrics subtitle capture, etc.

​
🚀 User Guide

  • By using this interface, you can generate corresponding audio content based on the input prompt.
  • It supports setting up loop playback effect, which is suitable for background music, ambient sounds, and other scenarios.
  • It allows specifying BPM (beats per minute) and pitch (Key) to facilitate control over the style of the generated result.
  • Optional feature to enable lyric subtitle capture for easier display or processing of lyric content later.
  • Supports asynchronous reception of task completion notifications through callback address.

​
📌 Usage Scenarios

  • 🎧 Background music creation
  • 🎮 Game sound effects or looped ambient sounds generation
  • 🌐 Integration of audio content platforms and creative tools

Authorizations

​
Authorization
string
header
required

🔑 API Authentication

All endpoints require authentication using Bearer Token.

Get API Key

  1. Visit the API Key Management Page to obtain your API Key

Usage

Add to request headers:

Authorization: Bearer YOUR_API_KEY

⚠️ Note:

  • Keep your API Key secure and do not share it with others
  • If you suspect your API Key has been compromised, reset it immediately from the management page

Body

application/json
​
prompt
string
required

Prompt text for sound generation. Maximum 500 characters.

Maximum string length: 500
Example:

"A soft rain ambience with distant thunder and gentle wind"

​
model
enum<string>
required

Model name. Sounds tasks only support V5.

Available options:
V5
Example:

"V5"

​
soundLoop
boolean
default:false

Whether to enable loop playback for the generated sound.

Example:

false

​
soundTempo
integer | null

BPM (beats per minute). If omitted, Auto is used.

Required range: 1 <= x <= 300
Example:

120

​
soundKey
enum<string>
default:Any

Pitch key of generated sound. Default is Any.

Available options:
Any,
Cm,
C#m,
Dm,
D#m,
Em,
Fm,
F#m,
Gm,
G#m,
Am,
A#m,
Bm,
C,
C#,
D,
D#,
E,
F,
F#,
G,
G#,
A,
A#,
B
Example:

"Any"

​
grabLyrics
boolean

Whether to fetch lyric subtitle data after task completion.

Example:

false

​
callBackUrl
string<uri>

Callback URL for asynchronous task completion notifications.

Example:

"https://api.example.com/callback"

Response

Request successful

​
code
enum<integer>

Status Codes

  • ✅ 200 - Request successful
  • ⚠️ 400 - Invalid parameters
  • ⚠️ 401 - Unauthorized access
  • ⚠️ 404 - Invalid request method or path
  • ⚠️ 405 - Rate limit exceeded
  • ⚠️ 413 - Theme or prompt too long
  • ⚠️ 429 - Insufficient credits
  • ⚠️ 430 - Your call frequency is too high. Please try again later.
  • ⚠️ 455 - System maintenance
  • ❌ 500 - Server error
Available options:
200,
400,
401,
404,
405,
413,
429,
430,
455,
500
Example:

200

​
msg
string

Error message when code != 200

Example:

"success"

​
data
object