Generate music
curl --request POST \
--url https://apistable.com/api/v1/tasks/create_task \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "suno_generate",
"input": {
"model": "V6",
"custom_mode": true,
"instrumental": false,
"title": "Paper boats at dawn",
"style": "Fingerpicked guitar, gentle brushed drums",
"lyrics": "[Verse]\nWe fold a map into a boat\nAnd let the morning carry it home"
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'suno_generate',
input: {
model: 'V6',
custom_mode: true,
instrumental: false,
title: 'Paper boats at dawn',
style: 'Fingerpicked guitar, gentle brushed drums',
lyrics: '[Verse]\nWe fold a map into a boat\nAnd let the morning carry it home'
}
})
};
fetch('https://apistable.com/api/v1/tasks/create_task', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://apistable.com/api/v1/tasks/create_task"
payload = {
"model": "suno_generate",
"input": {
"model": "V6",
"custom_mode": True,
"instrumental": False,
"title": "Paper boats at dawn",
"style": "Fingerpicked guitar, gentle brushed drums",
"lyrics": "[Verse]
We fold a map into a boat
And let the morning carry it home"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"code": 200,
"msg": "success",
"data": {
"task_id": "<string>"
}
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}API reference
Generate music
Describe the piece and supply a style or references. Custom mode lets you write the lyrics yourself.
POST
/
api
/
v1
/
tasks
/
create_task
Generate music
curl --request POST \
--url https://apistable.com/api/v1/tasks/create_task \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "suno_generate",
"input": {
"model": "V6",
"custom_mode": true,
"instrumental": false,
"title": "Paper boats at dawn",
"style": "Fingerpicked guitar, gentle brushed drums",
"lyrics": "[Verse]\nWe fold a map into a boat\nAnd let the morning carry it home"
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
model: 'suno_generate',
input: {
model: 'V6',
custom_mode: true,
instrumental: false,
title: 'Paper boats at dawn',
style: 'Fingerpicked guitar, gentle brushed drums',
lyrics: '[Verse]\nWe fold a map into a boat\nAnd let the morning carry it home'
}
})
};
fetch('https://apistable.com/api/v1/tasks/create_task', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://apistable.com/api/v1/tasks/create_task"
payload = {
"model": "suno_generate",
"input": {
"model": "V6",
"custom_mode": True,
"instrumental": False,
"title": "Paper boats at dawn",
"style": "Fingerpicked guitar, gentle brushed drums",
"lyrics": "[Verse]
We fold a map into a boat
And let the morning carry it home"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"code": 200,
"msg": "success",
"data": {
"task_id": "<string>"
}
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}{
"code": 123,
"msg": "<string>",
"data": null
}Operations are enabled individually by server configuration. Disabled operations return 503 without a task. Music credit deduction is currently disabled.
Using this operation
Describe the piece and supply a style or references. Custom mode lets you write the lyrics yourself.-
- Prepare the fields shown in the example below. Replace sample URLs and IDs with resources you can access.
-
- Set model to suno_generate and place the parameters inside input. Submit once and save the returned task_id.
-
- Query the saved task or receive its callback. A processing result is not a reason to submit the operation again.
- Read songs from result.data.data. Each song has its own APIstable id, which can be used as audio_id in a later task.
Create task
One operation, one execution item. The server records the provider, account, every upstream stage and output mapping. All IDs in the public API are APIstable IDs. Music credit deduction is not enabled.{
"model": "suno_generate",
"input": {
"model": "V6",
"custom_mode": true,
"instrumental": false,
"title": "Paper boats at dawn",
"style": "Fingerpicked guitar, gentle brushed drums",
"lyrics": "[Verse]\nWe fold a map into a boat\nAnd let the morning carry it home"
}
}
Parameter reference
| Field | Type | Required | Description and limits |
|---|---|---|---|
| lyrics | string | No / conditional | Lyrics, up to 5000 characters; takes precedence over prompt where both are accepted. maxLength: 5000 |
| prompt | string | No / conditional | Simple description: up to 3000 characters. In custom mode, lyrics takes precedence over prompt (up to 5000). maxLength: 5000 |
| style | string | No / conditional | Musical style, up to 1000 characters. Counts as one attachment in simple generation. maxLength: 1000 |
| negative_tags | string | No / conditional | Styles to exclude; required for adding instrumental backing or vocals. maxLength: 1000 |
| vocal_gender | string | No / conditional | m or f. A vocal tendency, not a guaranteed voice identity. Custom generation only. values: m, f |
| style_weight | number | No / conditional | Style influence, 0–1 with at most two decimal places. Custom generation only. min: 0; max: 1 |
| weirdness_constraint | number | No / conditional | Creativity constraint, 0–1 with at most two decimal places. Custom generation only. min: 0; max: 1 |
| audio_weight | number | No / conditional | Audio influence, 0–1 with at most two decimal places. Generation requires custom, non-instrumental mode. min: 0; max: 1 |
| variety | integer | No / conditional | Variety: integer 0–4, default 1 in custom generation. min: 0; max: 4 |
| persona_id | string | No / conditional | APIstable Voice or Persona ID; provider root and artist mapping remain server-side. maxLength: 200 |
| persona_model | string | No / conditional | style_persona or voice_persona; must match the resource’s actual origin. values: style_persona, voice_persona |
| max_mode | boolean | No / conditional | PayAPI extension. Max mode may increase supplier cost. APIstable credit deduction is currently disabled. default: false |
| model | string | Yes | Suno version: V6, V6_MINI or V6_WILD. Extension must match the generated source model. values: V6, V6_MINI, V6_WILD |
| custom_mode | boolean | Yes | Custom mode uses title, lyrics and style. Simple mode uses a prompt plus reference attachments. |
| instrumental | boolean | Yes | Generate instrumental music. Instrumental extensions omit prompt, lyrics and vocal_gender. |
| title | string | No / conditional | Title. Generate/cover: up to 80 characters; extend and other operations: up to 100. Required for custom generation. maxLength: 80 |
| duration | number | No / conditional | Requested duration, 10–360 seconds; custom generation only. Omit for automatic duration. min: 10; max: 360 |
| image_urls | array | No / conditional | Simple mode only. Up to 5 public JPEG/PNG/WebP/BMP URLs, at most 10 MB each. maxItems: 5 |
| video_urls | array | No / conditional | Simple mode only. One public MP4/MOV/WebM URL, at most 100 MB and 241 seconds. maxItems: 1 |
| audio_urls | array | No / conditional | Simple mode reference audio URLs. Each 6–1800 seconds, at most 500 MB. Total attachments including style and lyrics must be 1–10. maxItems: 10 |
Inputs and limits
Read the input schema below for every supported field, required flag, enum, range and default. Unknown parameters are rejected. URL fields accept public HTTPS URLs, never file objects.{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"lyrics": {
"type": "string",
"maxLength": 5000,
"description": "Lyrics, up to 5000 characters; takes precedence over prompt where both are accepted."
},
"prompt": {
"type": "string",
"maxLength": 5000,
"description": "Simple description: up to 3000 characters. In custom mode, lyrics takes precedence over prompt (up to 5000)."
},
"style": {
"type": "string",
"maxLength": 1000,
"description": "Musical style, up to 1000 characters. Counts as one attachment in simple generation."
},
"negative_tags": {
"type": "string",
"maxLength": 1000,
"description": "Styles to exclude; required for adding instrumental backing or vocals."
},
"vocal_gender": {
"type": "string",
"enum": [
"m",
"f"
],
"description": "m or f. A vocal tendency, not a guaranteed voice identity. Custom generation only."
},
"style_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Style influence, 0–1 with at most two decimal places. Custom generation only."
},
"weirdness_constraint": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Creativity constraint, 0–1 with at most two decimal places. Custom generation only."
},
"audio_weight": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Audio influence, 0–1 with at most two decimal places. Generation requires custom, non-instrumental mode."
},
"variety": {
"type": "integer",
"minimum": 0,
"maximum": 4,
"description": "Variety: integer 0–4, default 1 in custom generation."
},
"persona_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "APIstable Voice or Persona ID; provider root and artist mapping remain server-side."
},
"persona_model": {
"type": "string",
"enum": [
"style_persona",
"voice_persona"
],
"description": "style_persona or voice_persona; must match the resource's actual origin."
},
"max_mode": {
"default": false,
"type": "boolean",
"description": "PayAPI extension. Max mode may increase supplier cost. APIstable credit deduction is currently disabled."
},
"model": {
"type": "string",
"enum": [
"V6",
"V6_MINI",
"V6_WILD"
],
"description": "Suno version: V6, V6_MINI or V6_WILD. Extension must match the generated source model."
},
"custom_mode": {
"type": "boolean",
"description": "Custom mode uses title, lyrics and style. Simple mode uses a prompt plus reference attachments."
},
"instrumental": {
"type": "boolean",
"description": "Generate instrumental music. Instrumental extensions omit prompt, lyrics and vocal_gender."
},
"title": {
"type": "string",
"maxLength": 80,
"description": "Title. Generate/cover: up to 80 characters; extend and other operations: up to 100. Required for custom generation."
},
"duration": {
"type": "number",
"minimum": 10,
"maximum": 360,
"description": "Requested duration, 10–360 seconds; custom generation only. Omit for automatic duration."
},
"image_urls": {
"maxItems": 5,
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "Simple mode only. Up to 5 public JPEG/PNG/WebP/BMP URLs, at most 10 MB each."
},
"video_urls": {
"maxItems": 1,
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "Simple mode only. One public MP4/MOV/WebM URL, at most 100 MB and 241 seconds."
},
"audio_urls": {
"maxItems": 10,
"type": "array",
"items": {
"type": "string",
"format": "uri"
},
"description": "Simple mode reference audio URLs. Each 6–1800 seconds, at most 500 MB. Total attachments including style and lyrics must be 1–10."
}
},
"required": [
"model",
"custom_mode",
"instrumental"
],
"additionalProperties": false
}
Important conditions
- Song audio may be MP3 or M4A, matching the supplier media. M4A is never relabeled as MP3. Use suno_export_mp3 for an actual MP3. Unavailable optional covers are null; the audio remains usable.
- Custom generation requires title and at least one of style, lyrics or negative_tags. Simple generation requires 1–10 attachments, counting non-empty style and lyrics as one each; prompt alone is insufficient. Lyrics overrides prompt.
- Uploads remain available for 24 hours, generated files for 14 days, task details for 30 days. MP3 reuse keeps the source expiry. Valid Voice identity mappings survive task-log cleanup.
Result
The creation response is {code:200,msg:“success”,data:{task_id}}. Poll GET /api/v1/tasks/{task_id}. On success, data.result is an object matching the schema below; it is otherwise null. input remains a JSON string.{
"type": "object",
"required": [
"code",
"msg",
"data"
],
"properties": {
"code": {
"const": 200
},
"msg": {
"type": "string"
},
"data": {
"type": "object",
"required": [
"callbackType",
"task_id",
"data"
],
"properties": {
"callbackType": {
"const": "complete"
},
"task_id": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"audio_url",
"stream_audio_url",
"image_url",
"prompt",
"lyrics",
"model_name",
"title",
"createTime",
"duration",
"tags",
"source_audio_url",
"source_image_url",
"source_stream_audio_url"
],
"properties": {
"id": {
"type": "string"
},
"audio_url": {
"type": "string"
},
"stream_audio_url": {
"type": [
"string",
"null"
]
},
"image_url": {
"type": [
"string",
"null"
]
},
"prompt": {
"type": "string"
},
"lyrics": {
"type": [
"string",
"null"
]
},
"model_name": {
"type": [
"string",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"createTime": {
"type": [
"integer",
"null"
]
},
"duration": {
"type": [
"number",
"null"
]
},
"tags": {
"type": [
"string",
"null"
]
},
"source_audio_url": {
"type": "string"
},
"source_image_url": {
"type": [
"string",
"null"
]
},
"source_stream_audio_url": {
"type": [
"string",
"null"
]
}
}
}
}
}
}
}
}
Related workflows
Voice: all four steps File uploads CallbacksAuthorizations
Every valid key can submit and query its own account. Revoked keys are rejected.
Body
application/json