Sound effects API
Endpoint description
Sound effects create a few seconds of audio, not a song. They fit short sounds such as thunder, raindrops or an impact, and also work for transition effects, ambience and drum loops; most are under 5 seconds and the longest is around 20 seconds. Both one-shot and loop modes are supported.
Endpoint: POST /api/music/sounds
Billing: Paid, currently 0.6 CNY per call by default. The amount actually charged follows the current back-office price configuration.
Wait times and timeouts (important): this is a synchronous endpoint — the order is only accepted and handed to generation when the response arrives. Measured, most requests return in 1-3 seconds, about 10% take longer than 30 seconds, and the longest is about 230 seconds. Set your client timeout to 300 seconds or more; no response does not mean nothing was generated, and do not retry immediately after a timeout (that duplicates the order and charges again). If the connection dropped, confirm later with
GET /api/music/songs. See "Wait times and timeout settings" in the New API overview.
Request parameters
Headers
| Parameter | Type | Required | Notes |
|---|---|---|---|
| Authorization | string | yes | Bearer YOUR_API_KEY |
| Content-Type | string | yes | application/json |
Body parameters
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
| model | string | no | suno-v6 | Customer-facing model name: suno-v6, suno-v6-wild or suno-v6-mini |
| description | string | yes | - | Describe the sound you want; short English phrases work most reliably, for example cinematic whoosh transition, bright impact |
| title | string | no | - | Title; when omitted it can be generated from the description |
| type | string | no | one_shot | Type: one_shot (single) or loop (looping) |
| loop | boolean | no | false | Whether it loops; equivalent to setting type to loop |
| bpm | number | no | - | BPM; must be a number greater than 0. An invalid value returns 400 (invalid_sound_bpm) instead of being silently ignored |
| key | string | no | - | Musical key, in the form of a note name (C-B) plus an optional #/b plus an optional Major/Minor, for example C Major, C#m, Bb; empty or any means unrestricted. An invalid value returns 400 (invalid_sound_key) |
Request example
curl -X POST https://www.suno-api.io/api/music/sounds \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-v6",
"description": "cinematic whoosh transition, bright impact",
"title": "cinematic whoosh",
"type": "one_shot",
"loop": false,
"bpm": 120,
"key": "C"
}'
Response
An array of songs is returned; the fields are the same as the common song response fields in the New API overview.
Get an API key
Create an API key in the console after signing up. ¥0.6 per run returns 2 tracks, downloads are unlimited, and no phone number is required.
Get API key Back to overview