Skip to main content

Generate Music

POST 
/api/v1/generate

Generate music with or without lyrics using Suno's AI models.

Parameter Usage Guide​

  • When customMode is true (Custom Mode):

    • If instrumental is true: style and title are required
    • If instrumental is false: style, prompt, and title are required
    • prompt length limit: 3000 characters
    • style length limit: 200 characters
    • title length limit: 80 characters

  • When customMode is false (Non-custom Mode):

    • Only prompt is required regardless of instrumental setting
    • prompt length limit: 400 characters
    • Other parameters should be left empty

Developer Notes​

  1. Recommendation for First-Time Users: Start with customMode: false and instrumental: false, and only provide a prompt. This is the simplest setup to quickly test the API and experience the results.
  2. Generated files are retained for 15 days before being deleted
  3. Ensure all required fields are provided based on the customMode and instrumental settings to avoid errors
  4. Respect the character limits for prompt, style, and title to ensure successful processing
  5. Callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete)
  6. You can use the Get Music Generation Details endpoint to actively check task status instead of waiting for callbacks

Request​

Responses​

Request successful

Callbacks​

POST 
{request.body#/callBackUrl}

System will call this callback when audio generation is complete.

Callback Example​

{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "2fac****9f72",
    "data": [
      {
        "id": "8551****662c",
        "audio_url": "https://example.cn/****.mp3",
        "source_audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "source_stream_audio_url": "https://example.cn/****",
        "image_url": "https://example.cn/****.jpeg",
        "source_image_url": "https://example.cn/****.jpeg",
        "prompt": "[Verse] Night city lights shining bright",
        "model_name": "chirp-v3-5",
        "title": "Iron Man",
        "tags": "electrifying, rock",
        "createTime": "2025-01-01 00:00:00",
        "duration": 198.44
      },
      {
        "id": "bd15****1873",
        "audio_url": "https://example.cn/****.mp3",
        "source_audio_url": "https://example.cn/****.mp3",
        "stream_audio_url": "https://example.cn/****",
        "source_stream_audio_url": "https://example.cn/****",
        "image_url": "https://example.cn/****.jpeg",
        "source_image_url": "https://example.cn/****.jpeg",
        "prompt": "[Verse] Night city lights shining bright",
        "model_name": "chirp-v3-5",
        "title": "Iron Man",
        "tags": "electrifying, rock",
        "createTime": "2025-01-01 00:00:00",
        "duration": 228.28
      }
    ]
  }
}

Callbacks Responses​

Callback received successfully