POST /api/custom_generate
The server reads your Suno session from the SUNO_COOKIE environment variable. Pass a Cookie header containing a valid __client value to use a different Suno account on a per-request basis.
Request body
The song’s lyrics. You can use Suno section markers such as [Verse], [Chorus], [Bridge], and [Outro] to control song structure.
Comma-separated music style and genre tags that guide the sonic character of the output (e.g. "folk, acoustic guitar, female vocalist").
When true, generates music without vocals. The prompt lyrics are ignored.
model
string
default:"chirp-v3-5"
The Suno model version to use for generation.
When true, blocks until both clips reach streaming or complete status (up to 100 seconds). When false, clips are returned immediately in submitted / queued state.
Comma-separated style tags to avoid in the generated output (e.g. "heavy metal, distortion").
Response
An array of two AudioInfo objects. See Generate for the full field reference.
Unique identifier for the audio clip.
Title of the clip (matches the title you provided).
URL of the cover art image.
The lyrics used in the generated audio.
URL of the generated audio file. May be empty until status is streaming or complete.
URL of the generated video file.
ISO 8601 timestamp of clip creation.
The model used to generate this clip.
[].gpt_description_prompt
GPT description prompt field (empty for custom generation).
The lyrics prompt as stored in the clip’s metadata.
Generation status: submitted, queued, streaming, complete, or error.
Internal clip type as reported by Suno.
The style tags used for generation.
The negative style tags used for generation.
Duration of the audio clip in seconds.
Error description when status is error.
Error responses
| Status | Meaning |
|---|
400 | Bad request (e.g. missing required field) |
402 | Out of Suno credits — payment required |
500 | Internal server error |
Examples
Request
curl -X POST http://localhost:3000/api/custom_generate \
-H "Content-Type: application/json" \
-d '{
"prompt": "[Verse]\nI walk along the shore at dawn\nThe salt wind pulls me further on\nGrey waves are calling out my name\nI know I\'ll never be the same\n[Chorus]\nOcean wanderer, lost and free\nThe sea\'s the only home for me\nWhere the tide meets the open sky\nI let my restless spirit fly\n[Verse]\nA lighthouse blinks through morning haze\nI\'ve sailed these waters all my days\nNo harbor holds me long enough\nThe sea has always called my bluff",
"tags": "folk, acoustic guitar, female vocalist",
"title": "Ocean Wanderer",
"make_instrumental": false,
"model": "chirp-v3-5",
"wait_audio": true,
"negative_tags": "heavy metal, electronic"
}'
Response
[
{
"id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
"title": "Ocean Wanderer",
"image_url": "https://cdn1.suno.ai/image_c3d4e5f6-a7b8-9012-cdef-123456789012.jpeg",
"lyric": "[Verse]\nI walk along the shore at dawn\nThe salt wind pulls me further on\n[Chorus]\nOcean wanderer, lost and free\nThe sea's the only home for me",
"audio_url": "https://cdn1.suno.ai/c3d4e5f6-a7b8-9012-cdef-123456789012.mp3",
"video_url": "https://cdn1.suno.ai/c3d4e5f6-a7b8-9012-cdef-123456789012.mp4",
"created_at": "2024-01-15T11:05:00.000Z",
"model_name": "chirp-v3-5",
"gpt_description_prompt": "",
"prompt": "[Verse]\nI walk along the shore at dawn\nThe salt wind pulls me further on\n[Chorus]\nOcean wanderer, lost and free\nThe sea's the only home for me",
"status": "complete",
"type": "gen",
"tags": "folk, acoustic guitar, female vocalist",
"negative_tags": "heavy metal, electronic",
"duration": "132.0",
"error_message": null
},
{
"id": "d4e5f6a7-b8c9-0123-defa-234567890123",
"title": "Ocean Wanderer",
"image_url": "https://cdn1.suno.ai/image_d4e5f6a7-b8c9-0123-defa-234567890123.jpeg",
"lyric": "[Verse]\nI walk along the shore at dawn\nThe salt wind pulls me further on\n[Chorus]\nOcean wanderer, lost and free\nThe sea's the only home for me",
"audio_url": "https://cdn1.suno.ai/d4e5f6a7-b8c9-0123-defa-234567890123.mp3",
"video_url": "https://cdn1.suno.ai/d4e5f6a7-b8c9-0123-defa-234567890123.mp4",
"created_at": "2024-01-15T11:05:00.000Z",
"model_name": "chirp-v3-5",
"gpt_description_prompt": "",
"prompt": "[Verse]\nI walk along the shore at dawn\nThe salt wind pulls me further on\n[Chorus]\nOcean wanderer, lost and free\nThe sea's the only home for me",
"status": "complete",
"type": "gen",
"tags": "folk, acoustic guitar, female vocalist",
"negative_tags": "heavy metal, electronic",
"duration": "128.7",
"error_message": null
}
]
