Suno Music Generation

POST /v1/audio/generations

Compatibility endpoint:

POST /media/audio/generations

Query and cancel:

GET /v1/audio/generations/{id}
POST /v1/audio/generations/{id}/cancel

/media/audio/generations/{id} and /media/audio/generations/{id}/cancel are also supported.

Generate Music

{
  "model": "suno-music",
  "mode": "v5_5",
  "generation_type": "music_generation",
  "client_request_id": "suno-demo-001",
  "custom_mode": false,
  "prompt": "uplifting synth pop with bright drums and a confident chorus"
}

Custom instrumental:

{
  "model": "suno-music",
  "mode": "v5_5",
  "generation_type": "music_generation",
  "client_request_id": "suno-instrumental-001",
  "custom_mode": true,
  "instrumental": true,
  "style": "cinematic ambient pop, warm analog synths",
  "title": "Soft Horizon"
}

Rules:

• client_request_id is an optional idempotency key, up to 128 printable ASCII characters; under the same API key, the same request body returns the same job.
• mode currently supports only v5_5.
• custom_mode=false requires prompt, max 500 characters.
• custom_mode=true requires style and title.
• custom_mode=true with instrumental=false also requires prompt.
• Custom prompt is limited to 5000 characters, style to 1000 characters, and generation title to 80 characters.
• Additional Suno operation fields such as audio_id, task_id, duration_seconds, persona_id, persona_model, and callback-related fields are passed through when used with the supported operation types below.

Create responses use 202 Accepted:

{
  "code": 0,
  "message": "accepted",
  "data": {
    "id": "task_xxx",
    "status": "queued"
  }
}

Additional Suno Operations

The same endpoint also accepts these generation_type values:

generation_type	Use case
lyrics_generation	Generate lyrics
music_cover	Create a cover or style reinterpretation
upload_cover	Create a cover from uploaded or referenced audio
timestamped_lyrics	Generate or fetch timestamped lyrics
stem_separation	Split vocals/instruments or stems
wav_conversion	Convert generated audio to WAV
music_video	Create a music video from audio
add_vocals	Add vocals to an instrumental/audio source
add_instrumental	Add instrumental accompaniment
upload_extend	Extend uploaded or referenced audio

For these operation types, include the fields required by the upstream Suno-compatible provider, such as audio_url, audio_id, task_id, source_generation_id, source_track_index, lyrics, file_url, or provider-specific options. The gateway keeps the public task_xxx response ID and passes through operation-specific request fields to the upstream provider.

When source_generation_id, task_id, sourceGenerationId, or taskId is a public task_xxx ID owned by the same account, the gateway resolves it to the upstream task ID before forwarding.

Extend Music

Use the platform task_xxx ID as source_generation_id; do not send raw task IDs from other systems.

{
  "model": "suno-music",
  "mode": "v5_5",
  "generation_type": "music_extend",
  "client_request_id": "suno-extend-001",
  "source_generation_id": "task_xxx",
  "source_track_index": 0,
  "default_param_flag": false
}

Custom extension:

{
  "model": "suno-music",
  "mode": "v5_5",
  "generation_type": "music_extend",
  "client_request_id": "suno-extend-custom-001",
  "source_generation_id": "task_xxx",
  "source_track_index": 0,
  "default_param_flag": true,
  "continue_at_seconds": 42.5,
  "prompt": "continue with a bigger second chorus and tighter drums",
  "style": "cinematic synth pop",
  "title": "Soft Horizon Extended"
}

Extension rules:

• source_generation_id must be a completed suno-music job ID owned by the same account.
• source_track_index is required and starts at 0.
• When default_param_flag=false, only send source_generation_id and source_track_index; do not include prompt, style, title, or continue_at_seconds.
• When default_param_flag=true, prompt, style, title, and continue_at_seconds are required.
• continue_at_seconds must be greater than 0; if the source track returned duration_seconds, it must also be less than that source track duration.
• Extension title is limited to 100 characters.

Completed Result

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "task_xxx",
    "kind": "audio",
    "status": "completed",
    "model": "suno-music",
    "mode": "v5_5",
    "family": "suno",
    "generation_type": "music_generation",
    "poll_url": "/v1/audio/generations/task_xxx",
    "cancel_url": "/v1/audio/generations/task_xxx/cancel",
    "result": {
      "outputs": ["https://static.example.com/media/suno-output.mp3"],
      "tracks": [
        {
          "index": 0,
          "title": "Soft Horizon",
          "duration_seconds": 123.4,
          "cover_url": "https://example.com/cover.jpg"
        }
      ]
    }
  }
}

Notes:

• result.outputs contains playable or downloadable audio URLs.
• result.tracks contains per-track result metadata such as title, cover, duration, lyrics/prompt, and tags when returned by the platform.
• Other operations may return additional fields such as lyrics, timestamped_lyrics, stems, wav_url, video_url, or provider-specific data. Cost and internal storage fields are removed from the public response.