Music GenerationtaskType: generate_music

Generate Music

Generate AI music from text prompts with full control over genre, mood, tempo, and vocals. Supports custom mode with tags and lyrics, or simple mode with natural language descriptions. Returns high-quality stereo audio tracks.

POST/api/v1/createTask

Test in Playground

Usage Guide

This endpoint creates music based on your text prompt.
Multiple variations will be generated for each request.
You can control detail level with custom mode and instrumental settings.

Supported AI Models

3 Official Models

V6DEFAULT

Powerful and versatile, Refined.

V6_WILD

Best for experimental ideas.

V6_MINI

More efficient version of V6.

Character Limits: style: 1000 chars | lyrics: 5000 chars | title: 80 chars● Instant GPU synthesis

Parameter Details & Mode Rules

Always Required Fields:

custom_mode, instrumental, model

In Custom Mode (custom_mode: true):

title is required, maximum 80 characters.
prompt is optional; when provided, it is used strictly as lyrics and sung in the generated track. If lyrics is also provided, lyrics takes priority.
At least one of style, lyrics, or negative_tags must be provided; generation is rejected if all are empty.
If instrumental: true: generate instrumental music (no vocals).
If instrumental: false: use lyrics as singing vocals.

In Non-Custom Mode (custom_mode: false):

prompt serves as the core musical idea (lyrics generated automatically, max 3000 characters).
Reference media attachments: image_urls, video_urls, and audio_urls are only valid in this mode.
Total attachments must not exceed 10 (style + lyrics + media URLs).

Developer Notes

Recommendation for new users: Start with custom_mode: false for simpler usage.
File Retention: Generated audio and cover files are permanently retained for 14 days on edge storage.
Callback Process: Three-stage lifecycle: text (lyric plan ready), first (first variation track synthesized), and complete (all variations ready).

Authentication & Headers

Header	Requirement	Description
Authorization	required	Bearer YOUR_API_KEY Secret API Key obtained from dashboard.
Content-Type	required	application/json Request payload format.

Header

Requirement

Description

Authorization

required

Bearer YOUR_API_KEY

Secret API Key obtained from dashboard.

Content-Type

required

application/json

Request payload format.

Request Body Schema

20 fields

modelstringrequired

default:V6

AI model to use for music generation. V6 is the refined default, V6_WILD for experimental ideas, and V6_MINI for rapid lightweight generation.

Allowed options:

"V6""V6_WILD""V6_MINI"

custom_modebooleanrequired

default:true

Determines whether custom mode is enabled. If true, allows detailed control over style, title, and lyrics.

instrumentalbooleanrequired

default:false

Whether the generated track should be purely instrumental without vocals.

promptstringoptional

Description of the desired audio content. Used as lyrics in custom mode; used as core idea in non-custom mode (maximum 3000 characters).

titlestringoptional

Title for the generated track (maximum 80 characters, required when custom_mode is true).

stylestringoptional

Music genre, mood, or instrument style tags. Maximum 1000 characters for V6 models.

lyricsstringoptional

Explicit lyrics text. Maximum 5000 characters for V6 models. In custom mode, takes priority over prompt.

negative_tagsstringoptional

Genres, instruments, or acoustic traits to exclude from the generated audio.

durationnumberoptional

default:20

Audio duration in seconds. Range: 10–360 seconds (default: 20s).

vocal_genderstringoptional

Preferred vocal timbre: 'm' for male, 'f' for female. Only effective when custom_mode is true.

Allowed options:

"m""f"

style_weightnumberoptional

default:0.65

Strength of adherence to the specified style. Range 0–1, up to 2 decimal places. Only effective when custom_mode is true.

weirdness_constraintnumberoptional

default:0.65

Creative/experimental deviation. Range 0–1, up to 2 decimal places. Only effective when custom_mode is true.

audio_weightnumberoptional

default:0.65

Relative weight of audio features. Range 0–1, up to 2 decimal places. Only effective when custom_mode is true.

varietynumberoptional

default:1

Diversity of generated results: 0 (off, exact style), 1 (normal default, balanced), 2 (high, distinct styles), 3 (extra, bold exploration), 4 (max, maximum variation).

Allowed options:

"0""1""2""3""4"

persona_idstringoptional

Persona ID or Voice ID to apply consistent vocal character.

persona_modelstringoptional

Persona model type: style_persona or voice_persona. Supported in V6 models.

Allowed options:

"style_persona""voice_persona"

image_urlsarrayoptional

Image references. Only effective when custom_mode is false. Up to 5 images, max 10MB each (jpeg, png, webp, bmp).

video_urlsarrayoptional

Video references. Only effective when custom_mode is false. Up to 1 file, max 100MB, duration <= 241s (mp4, mov, webm).

audio_urlsarrayoptional

Audio references. Only effective when custom_mode is false. Duration between 6s and 30m, max 500MB.

callBackUrlstringoptional

Public Webhook URL to receive task completion notifications when audio generation is finished.

When Callbacks Are Sent

The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:

Stage 1 (text): Lyrics and musical arrangement plan generated
Stage 2 (first): First audio variation synthesis complete and ready for streaming
Stage 3 (complete): All variation tracks generated and uploaded to high-speed CDN

Webhook Payload Format

Response Body(200 status)

{
  "code": 200,
  "msg": "success",
  "data": {
    "callbackType": "complete",
    "task_id": "5c79****be8e",
    "data": [
      {
        "id": "track_a1b2c3d4",
        "audio_url": "https://cdn.sunoapi.top/audio/track_a1b2c3d4.mp3",
        "image_url": "https://cdn.sunoapi.top/covers/track_a1b2c3d4.jpg",
        "title": "Peaceful Piano Meditation",
        "duration": 185.4,
        "model_name": "V6"
      },
      {
        "id": "track_e5f6g7h8",
        "audio_url": "https://cdn.sunoapi.top/audio/track_e5f6g7h8.mp3",
        "image_url": "https://cdn.sunoapi.top/covers/track_e5f6g7h8.jpg",
        "title": "Peaceful Piano Meditation",
        "duration": 192.1,
        "model_name": "V6"
      }
    ]
  }
}

Callback Payload Fields

Field	Type	Description
`data.callbackType`	string	Callback stage: "text", "first", or "complete"
`data.task_id`	string	Unique task identifier assigned at submission
`data.data`	array	Array of generated tracks with URLs, duration, and metadata

Receiver Implementation Example

Webhook Receiver

// Next.js App Router Webhook Receiver (/api/webhook/suno/route.ts)
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { callbackType, task_id, data } = payload.data || {};

  if (callbackType === 'complete') {
    console.log(`Task ${task_id} completed with ${data?.length} tracks`);
    // Save generated tracks to database...
  }

  return NextResponse.json({ received: true });
}

Webhook Security Recommendation

Always verify incoming webhook payloads on your server. Respond with a 200 OK immediately after parsing the payload to prevent redundant delivery retries from the webhook dispatcher.

Request Sample

curl -X POST "https://api.sunoapi.top/api/v1/createTask" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "V6",
    "custom_mode": true,
    "instrumental": false,
    "title": "Peaceful Piano Meditation",
    "style": "Classical, Piano, Calming",
    "prompt": "Soft piano chords flowing gently in a quiet sanctuary...",
    "callBackUrl": "https://api.yourdomain.com/webhook/suno"
  }'

Response Body(200 status)

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

Previous EndpointReplace Music Section Callbacks Next EndpointExtend Music

Ready to integrate Generate Music API?

Create your free account, obtain your API key, and get 5 free generation credits.

Generate Secret Key