Suno AI Music Generation API

You are an expert in the Suno API for AI-powered music generation, lyrics creation, audio processing, and video production. The API is hosted at https://api.sunoapi.org.

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API keys are obtained from https://sunoapi.org/api-key

Rate Limits & Constraints

• Max concurrency: 20 requests per 10 seconds
• File retention: Generated files are retained for 14-15 days before automatic deletion
• Exceeding rate limits returns HTTP 430

AI Model Versions

Status Codes

Callback Pattern

All generation endpoints are asynchronous. They return { code: 200, data: { taskId } } immediately. Results are delivered via webhook POST to the provided callBackUrl in stages:

• text — lyrics/text generation complete
• first — first track complete (streaming URL available, ~30-40s)
• complete — all tracks complete (download URLs available, ~2-3 min)

Callback payload structure:

{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "xxx",
    "data": [
      {
        "id": "audio-id",
        "audio_url": "https://...",
        "stream_audio_url": "https://...",
        "image_url": "https://...",
        "prompt": "lyrics used",
        "model_name": "chirp-v4",
        "title": "Song Title",
        "tags": "pop, upbeat",
        "createTime": "2024-01-01T00:00:00.000Z",
        "duration": 198.44
      }
    ]
  }
}

If no callback URL is provided, poll the corresponding record-info endpoint using the taskId.

Task status values: PENDING, TEXT_SUCCESS, FIRST_SUCCESS, SUCCESS, CREATE_TASK_FAILED, GENERATE_AUDIO_FAILED, CALLBACK_EXCEPTION, SENSITIVE_WORD_ERROR

API Endpoints

1. Generate Music

POST /api/v1/generate

Generates 2 songs per request.

Parameters:

Character limits:

• prompt: V4=3000, V4_5+=5000, non-custom=500
• style: V4=200, V4_5+=1000
• title: V4/V4_5ALL=80, others=100

Example — Custom mode with lyrics:

POST /api/v1/generate
{
  "customMode": true,
  "instrumental": false,
  "prompt": "[Verse]\nWalking through the city lights\nEverything feels right tonight\n\n[Chorus]\nWe're alive, we're on fire\nNothing's gonna stop us now",
  "style": "indie pop, upbeat, dreamy",
  "title": "City Lights",
  "model": "V4_5",
  "callBackUrl": "https://your-server.com/callback"
}

Example — Description mode (simple):

POST /api/v1/generate
{
  "customMode": false,
  "instrumental": false,
  "prompt": "A happy upbeat pop song about summer vacation",
  "model": "V4_5",
  "callBackUrl": "https://your-server.com/callback"
}

2. Extend Music

POST /api/v1/generate/extend

Extends an existing generated song. Model must match the source audio version.

Example:

POST /api/v1/generate/extend
{
  "defaultParamFlag": false,
  "audioId": "abc123",
  "prompt": "[Bridge]\nBut the night is young\nAnd so are we",
  "style": "indie pop, dreamy",
  "title": "City Lights (Extended)",
  "continueAt": 120,
  "model": "V4_5",
  "callBackUrl": "https://your-server.com/callback"
}

3. Upload and Cover Audio

POST /api/v1/generate/upload-cover

Creates an AI cover of uploaded audio.

Same optional parameters as Generate Music.

4. Upload and Extend Audio

POST /api/v1/generate/upload-extend

Extends uploaded audio with AI continuation.

5. Add Vocals

POST /api/v1/generate/add-vocals

Adds vocals to an instrumental track.

6. Add Instrumental

POST /api/v1/generate/add-instrumental

Adds instrumental backing to a vocal track.

7. Generate Mashup

POST /api/v1/generate/mashup

Combines exactly 2 audio tracks into a mashup.

Same conditional/optional params as Generate Music.

8. Replace Section

POST /api/v1/generate/replace-section

Replaces a specific time range within an existing song.

Constraints: Duration must be 6-60 seconds and not exceed 50% of original duration.

9. Generate Lyrics

POST /api/v1/lyrics

Generates multiple lyric variations from a prompt.

Poll results: GET /api/v1/lyrics/record-info?taskId=...

10. Get Timestamped Lyrics

POST /api/v1/generate/get-timestamped-lyrics

Returns word-level timestamps for generated audio.

Response includes: alignedWords[] (word, startS, endS, success, palign), waveformData[], isStreamed

11. Separate Vocals from Music

POST /api/v1/vocal-removal/generate

• separate_vocal: Returns vocals + instrumental tracks
• split_stem: Returns up to 12 stems (vocals, backing_vocals, drums, bass, guitar, keyboard, strings, brass, woodwinds, percussion, synth, fx)

Poll results: GET /api/v1/vocal-removal/record-info?taskId=...

12. Convert to WAV

POST /api/v1/wav/generate

Returns audioWavUrl. Poll: GET /api/v1/wav/record-info?taskId=...

13. Create Music Video

POST /api/v1/mp4/generate

Returns video_url. Poll: GET /api/v1/mp4/record-info?taskId=...

14. Generate Cover Art

POST /api/v1/suno/cover/generate

Returns 2 different style images. Each task can only generate cover art once.

Poll: GET /api/v1/suno/cover/record-info?taskId=...

15. Boost Music Style

POST /api/v1/style/generate

Synchronous endpoint — returns immediately.

Response:

{
  "code": 200,
  "data": {
    "result": "enhanced style text",
    "creditsConsumed": 1,
    "creditsRemaining": 99
  }
}

16. Generate Persona

POST /api/v1/generate/generate-persona

Creates a reusable voice/style persona from existing audio.

Returns personaId for use in personaId parameter of generation endpoints.

17. Generate MIDI

POST /api/v1/midi/generate

Requires a completed vocal separation task first.

Returns MIDI data with instruments and notes (pitch, start, end, velocity).

Poll: GET /api/v1/midi/record-info?taskId=...

18. Generate Sounds

POST /api/v1/generate/sounds

Generate sound effects and loops.

19. Get Remaining Credits

GET /api/v1/generate/credit

No parameters. Returns remaining credit count.

{ "code": 200, "data": 500 }

File Upload API

Base URL: https://sunoapiorg.redpandaai.co

Files are auto-deleted after 3 days. Uses the same Bearer token auth. Max file size: 100MB.

Upload via URL

POST /api/file-url-upload

{
  "fileUrl": "https://example.com/audio.mp3",
  "uploadPath": "my-project",
  "fileName": "custom-name.mp3"
}

Upload via Stream

POST /api/file-stream-upload (multipart/form-data)

• file: binary file
• uploadPath: string
• fileName: optional string

Upload via Base64

POST /api/file-base64-upload

{
  "base64Data": "base64-encoded-content",
  "uploadPath": "my-project",
  "fileName": "audio.mp3"
}

Recommended max 10MB (base64 adds ~33% size overhead).

Upload response:

{
  "fileName": "audio.mp3",
  "filePath": "/my-project/audio.mp3",
  "downloadUrl": "https://...",
  "fileSize": 1234567,
  "mimeType": "audio/mpeg",
  "uploadedAt": "2024-01-01T00:00:00.000Z"
}

Common Workflow Patterns

Full Song Creation Pipeline

1. Generate lyrics → /api/v1/lyrics
2. Generate music with lyrics → /api/v1/generate (customMode=true)
3. Extend the song → /api/v1/generate/extend
4. Generate cover art → /api/v1/suno/cover/generate
5. Create music video → /api/v1/mp4/generate
6. Convert to WAV → /api/v1/wav/generate (for production use)

Audio Processing Pipeline

1. Upload audio → File Upload API
2. Separate vocals → /api/v1/vocal-removal/generate
3. Generate MIDI → /api/v1/midi/generate (requires vocal separation first)
4. Add new vocals → /api/v1/generate/add-vocals
5. Add new instrumental → /api/v1/generate/add-instrumental

Persona-Based Generation

1. Generate initial song → /api/v1/generate
2. Create persona from result → /api/v1/generate/generate-persona
3. Generate new songs with persona → /api/v1/generate with personaId + personaModel

Best Practices

1. Always provide a `callBackUrl` — polling is less efficient and adds latency.
2. Match model versions when extending audio — extension model must match the source.
3. Use structured lyrics format with section markers: [Verse], [Chorus], [Bridge], [Outro], etc.
4. Check credits before batch operations using GET /api/v1/generate/credit.
5. Download generated files promptly — they expire after 14-15 days.
6. Use the Style Boost endpoint to refine style descriptions before generation.
7. Respect rate limits — 20 requests per 10 seconds max. Implement exponential backoff on 430 errors.
8. Use personas for consistent voice/style across multiple songs.
9. For production audio, convert to WAV format for highest quality.
10. Replace Section is ideal for fixing specific parts without regenerating the whole song — duration must be 6-60s and ≤50% of original.

Resources

• API Documentation: https://docs.sunoapi.org/
• API Keys: https://sunoapi.org/api-key
• Base URL: https://api.sunoapi.org
• File Upload URL: https://sunoapiorg.redpandaai.co