> ## Documentation Index > Fetch the complete documentation index at: https://docs.apistable.com/llms.txt > Use this file to discover all available pages before exploring further. # Generate music > Describe the piece and supply a style or references. Custom mode lets you write the lyrics yourself. > 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. * 2. Set model to suno\_generate and place the parameters inside input. Submit once and save the returned task\_id. * 3. 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. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "$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. ```json theme={null} { "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. ## Related workflows [Voice: all four steps](https://docs.apistable.com/en/suno-voice-workflow.md) [File uploads](https://docs.apistable.com/en/file-upload.md) [Callbacks](https://docs.apistable.com/en/webhooks.md) ## OpenAPI ````yaml openapi-suno-generate.json POST /api/v1/tasks/create_task openapi: 3.1.0 info: title: APIstable API version: 1.0.0-preview description: >- Public /api/v1 protocol. Valid API keys have the same account-scoped access. No client submission idempotency or max_credits. Enabled Suno operations use PayAPI and durable task processing. Media uses R2: uploads 24 hours, generated files 14 days, task logs 30 days. Music credit deduction is disabled. Unconfigured operations and LLM return 503. servers: - url: https://apistable.com description: APIstable API security: [] paths: /api/v1/tasks/create_task: post: summary: Generate music description: >- Describe the piece and supply a style or references. Custom mode lets you write the lyrics yourself. operationId: suno_generate requestBody: required: true content: application/json: schema: type: object required: - model - input additionalProperties: false properties: model: type: string enum: - suno_generate example: suno_generate input: $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 callback_url: type: string format: uri description: >- Optional public HTTPS endpoint for signed completion callbacks; no redirects or private IPs. example: 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 responses: '200': description: Accepted task. Poll the common task endpoint or use callback_url. content: application/json: schema: type: object required: - code - msg - data additionalProperties: false properties: code: const: 200 msg: const: success data: type: object required: - task_id additionalProperties: false properties: task_id: type: string '400': description: >- 40001 invalid JSON, 40002 invalid input/callback, 40003 unsupported parameter. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Invalid or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: '40201: Insufficient credits (live acceptance).' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '40401: Unknown model or resource not found in this account.' content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: '40901: Resource belongs to a different provider account.' content: application/json: schema: $ref: '#/components/schemas/Error' '410': description: '41001: Source audio or temporary resource has expired.' content: application/json: schema: $ref: '#/components/schemas/Error' '413': description: '41301: Request too large.' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: '42201: Requested music combination is not enabled.' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '42901: Rate/concurrency limit (live acceptance).' content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: '50301: Service/provider unavailable. No live submission or charge.' content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: Error: type: object required: - code - msg - data properties: code: type: integer msg: type: string data: type: 'null' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Every valid key can submit and query its own account. Revoked keys are rejected. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.