Generate music

curl --request POST \
  --url https://apistable.ai/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.ai/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.ai/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
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

{
  "code": 123,
  "msg": "<string>",
  "data": null
}

POST

api

tasks

create_task

Generate music

curl --request POST \
  --url https://apistable.ai/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.ai/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.ai/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
}

{
  "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.

1. Prepare the fields shown in the example below. Replace sample URLs and IDs with resources you can access.
1. Set model to suno_generate and place the parameters inside input. Submit once and save the returned task_id.
1. 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

Send model and input to the common task endpoint. callback_url is an optional top-level public HTTPS address. All resource IDs are APIstable IDs owned by your account. Music credit deduction is currently disabled.

{
  "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"
  }
}

Acceptance response

HTTP 200 confirms acceptance, not completion. Query GET /api/v1/tasks/{task_id} until data.status is succeeded or failed. Read data.result only after success; a failed task has its error in data.message.

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "YOUR_TASK_ID"
  }
}

Parameter reference

Field	Type	Required	Description and limits
lyrics	string	No / conditional	Up to 5000 characters. Custom mode uses this instead of prompt when present; simple mode uses it alongside prompt and counts non-empty lyrics as one attachment. maxLength: 5000
prompt	string	No / conditional	Simple mode: description up to 3000 characters, used alongside lyrics. Custom mode: fallback lyrics up to 5000 characters, used only when lyrics is omitted. 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. When generating music, requires custom mode. values: m, f
style_weight	number	No / conditional	Style influence, 0–1 with at most two decimal places. When generating music, requires custom mode. min: 0; max: 1
weirdness_constraint	number	No / conditional	Creativity constraint, 0–1 with at most two decimal places. When generating music, requires custom mode. 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 MiB each. maxItems: 5
video_urls	array	No / conditional	Simple mode only. One public MP4/MOV/WebM URL, at most 100 MiB and 241 seconds. maxItems: 1
audio_urls	array	No / conditional	Simple mode reference audio URLs. Each 6–1800 seconds, at most 500 MiB. Total attachments including style and lyrics must be 1–10. maxItems: 10

Inputs and limits

The schema lists supported fields, types and basic limits. Also follow Important conditions: cross-field and source-resource checks are not fully represented in JSON Schema. 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": "Up to 5000 characters. Custom mode uses this instead of prompt when present; simple mode uses it alongside prompt and counts non-empty lyrics as one attachment."
    },
    "prompt": {
      "type": "string",
      "maxLength": 5000,
      "description": "Simple mode: description up to 3000 characters, used alongside lyrics. Custom mode: fallback lyrics up to 5000 characters, used only when lyrics is omitted."
    },
    "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. When generating music, requires custom mode."
    },
    "style_weight": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Style influence, 0–1 with at most two decimal places. When generating music, requires custom mode."
    },
    "weirdness_constraint": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Creativity constraint, 0–1 with at most two decimal places. When generating music, requires custom mode."
    },
    "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 MiB 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 MiB 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 MiB. Total attachments including style and lyrics must be 1–10."
    }
  },
  "required": [
    "model",
    "custom_mode",
    "instrumental"
  ],
  "additionalProperties": false
}

Important conditions

Custom mode requires a non-blank title and at least one non-blank style, lyrics or negative_tags. Omit image_urls, video_urls and audio_urls entirely, including empty arrays. persona_model requires persona_id.
Simple mode requires 1–10 attachments: count each image/video/audio URL and each non-empty style or lyrics field. prompt alone is insufficient. Omit all five control fields and duration. In simple mode prompt describes the music while lyrics supplies lyrics; in custom mode lyrics takes precedence over prompt.
Audio references: 6–1800 seconds, up to 500 MiB each. Images: JPEG/PNG/WebP/BMP up to 10 MiB each. Videos: MP4/MOV/WebM up to 100 MiB and 241 seconds. audio_weight requires custom, non-instrumental mode.
Audio URL inputs must contain readable MP3/WAV/FLAC/OGG/M4A/AAC audio with positive duration; the limit is 500 MiB per file. URLs must be publicly accessible HTTPS on port 443, without embedded credentials or private-network addresses. Keep them accessible until the task finishes.
Song audio may be MP3 or M4A. Use suno_export_mp3 for an actual MP3 file. Unavailable optional cover art may be null; audio remains usable.
Uploaded files last 24 hours, generated files 14 days and task details 30 days. Reused files keep their original expiry. Valid Voice/Persona identity mappings are separate from task-log cleanup. Download files you need to retain.

Result schema

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"
                ]
              }
            }
          }
        }
      }
    }
  }
}

Song duration is in seconds; task duration is in milliseconds. createTime is a Unix timestamp in milliseconds or null. Current stream_audio_url and source_stream_audio_url are null. source_audio_url/source_image_url refer to the same APIstable-hosted copies as audio_url/image_url, not provider links. Process the actual song array; upload registration does not imply two newly generated songs.

Voice: all four steps File uploads Callbacks

Authorizations

Authorization

string

header

required

Every valid key can submit and query its own account. Revoked keys are rejected.

Body

application/json

model

enum<string>

required

Available options:

suno_generate

Example:

"suno_generate"

input

object

required

Show child attributes

callback_url

string<uri>

Optional public HTTPS endpoint for signed completion callbacks; no redirects or private IPs.

Response

Accepted task. Poll the common task endpoint or use callback_url.

code

any

required

msg

any

required

data

object

required

Show child attributes

Getting started with APIstable

Market

Generate music

Using this operation

Create task

Acceptance response

Parameter reference

Inputs and limits

Important conditions

Result schema

Authorizations

Body

Response

​Using this operation

​Create task

​Acceptance response

​Parameter reference

​Inputs and limits

​Important conditions

​Result schema

​Related workflows

Authorizations

Body

Response

Using this operation

Create task

Acceptance response

Parameter reference

Inputs and limits

Important conditions

Result schema

Related workflows