Suno AI -- Music Generation

The Suno AI API lets you generate music and lyrics automatically using artificial intelligence. The system uses an asynchronous model: you submit a request to get a taskId, then poll to retrieve the results.

Base URL

code

https://api.shopaikey.com

Authentication

All endpoints require the header:

code

Authorization: Bearer <your-api-key>

Usage Flow

code

1. POST /suno/submit/music  →  Receive taskId
                ↓
2. GET  /suno/fetch/{taskId}  →  Poll every 3s until status = "SUCCESS"
                ↓
3. Get audio_url, image_url from the result

1. Generate Music

Endpoint: POST /suno/submit/music

Submit a music generation request. Suno AI creates 2 tracks per request. There are 2 input modes:

Description mode: Describe your idea in natural language; GPT will generate the prompt.
Lyrics mode: Directly input lyrics in [Verse], [Chorus]... format.

Request Body Parameters

Parameter	Type	Required	Description
`mv`	string	Yes	Model version. See model list below
`gpt_description_prompt`	string	No*	Music description (description mode). GPT will auto-generate lyrics and prompt
`prompt`	string	No*	Direct lyrics input (lyrics mode)
`title`	string	No	Song title
`tags`	string	No	Music genre, e.g.: `pop, upbeat, electronic`
`make_instrumental`	boolean	No	`true` for instrumental only. Default: `false`

* Note: At least one of gpt_description_prompt or prompt must be provided.

cURL Example — Description Mode

code

curl -X POST 'https://api.shopaikey.com/suno/submit/music' \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "mv": "chirp-hawk",
    "gpt_description_prompt": "An upbeat pop song about summer and the ocean",
    "title": "Summer Vibes",
    "tags": "pop, summer, upbeat"
  }'

cURL Example — Lyrics Mode

code

curl -X POST 'https://api.shopaikey.com/suno/submit/music' \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "mv": "chirp-hawk",
    "prompt": "[Verse 1]\nSunlight softly falls on my shoulder\nThe wind carries the sound of ocean waves\n\n[Chorus]\nOh summer, where are you...",
    "title": "Oh Summer",
    "tags": "pop, ballad",
    "make_instrumental": false
  }'

JavaScript Example

code

const response = await fetch('https://api.shopaikey.com/suno/submit/music', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <your-api-key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    mv: 'chirp-hawk',
    gpt_description_prompt: 'An upbeat pop song about summer and the ocean',
    title: 'Summer Vibes',
    tags: 'pop, summer, upbeat',
  }),
});

const data = await response.json();
// data.code === "success"
const taskId = data.data;
console.log('Task ID:', taskId);

Response

code

{
  "code": "success",
  "data": "task_abc123xyz"
}

Field	Type	Description
`code`	string	`"success"` if submission succeeded
`data`	string	`taskId` to poll for results
`message`	string	Error message (when `code !== "success"`)

2. Generate Lyrics

Endpoint: POST /suno/submit/lyrics

Generate lyrics from a topic description. Returns lyrics in verse/chorus structure.

Request Body Parameters

Parameter	Type	Required	Description
`prompt`	string	Yes	Description of the lyrics theme
`title`	string	No	Song title
`tags`	string	No	Music genre, e.g.: `pop, romantic`

cURL Example

code

curl -X POST 'https://api.shopaikey.com/suno/submit/lyrics' \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Write lyrics about overcoming hardships and standing up after failure",
    "title": "Rise Up",
    "tags": "pop, inspirational"
  }'

JavaScript Example

code

const response = await fetch('https://api.shopaikey.com/suno/submit/lyrics', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <your-api-key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'Write lyrics about overcoming hardships and standing up after failure',
    title: 'Rise Up',
  }),
});

const data = await response.json();
const taskId = data.data;

Response

code

{
  "code": "success",
  "data": "task_def456uvw"
}

3. Retrieve Task Results

Endpoint: GET /suno/fetch/{taskId}

Poll this endpoint every 3 seconds until status is "SUCCESS" or "FAILED".

cURL Example

code

curl 'https://api.shopaikey.com/suno/fetch/task_abc123xyz' \
  -H 'Authorization: Bearer <your-api-key>'

JavaScript Example — Auto Poll

code

async function pollTask(taskId, apiKey, intervalMs = 3000) {
  return new Promise((resolve, reject) => {
    const interval = setInterval(async () => {
      const response = await fetch(
        `https://api.shopaikey.com/suno/fetch/${taskId}`,
        { headers: { Authorization: `Bearer ${apiKey}` } }
      );
      const result = await response.json();

      if (result.code !== 'success' || !result.data) return;

      const status = result.data.status?.toLowerCase();
      if (status === 'success') {
        clearInterval(interval);
        resolve(result.data.data); // array of songs
      } else if (status === 'failed') {
        clearInterval(interval);
        reject(new Error(result.data.fail_reason || 'Failed'));
      }
      // Continue polling if status is submitted / queueing / processing
    }, intervalMs);
  });
}

// Usage
const songs = await pollTask('task_abc123xyz', '<your-api-key>');
console.log('Audio URL:', songs[0].audio_url);

Response — Music Generation

Processing:

code

{
  "code": "success",
  "data": {
    "status": "PROCESSING",
    "fail_reason": null,
    "data": []
  }
}

Completed:

code

{
  "code": "success",
  "data": {
    "status": "SUCCESS",
    "fail_reason": null,
    "data": [
      {
        "id": "clip_abc123",
        "clip_id": "clip_abc123",
        "audio_url": "https://cdn.suno.ai/audio/clip_abc123.mp3",
        "video_url": "https://cdn.suno.ai/video/clip_abc123.mp4",
        "image_url": "https://cdn.suno.ai/image/clip_abc123.jpg",
        "title": "Summer Vibes",
        "tags": "pop, summer, upbeat",
        "prompt": "[Verse 1]\nGolden sunlight spreads across the sand...",
        "model_name": "chirp-hawk",
        "duration": 118.4
      },
      {
        "id": "clip_def456",
        "clip_id": "clip_def456",
        "audio_url": "https://cdn.suno.ai/audio/clip_def456.mp3",
        "video_url": "https://cdn.suno.ai/video/clip_def456.mp4",
        "image_url": "https://cdn.suno.ai/image/clip_def456.jpg",
        "title": "Summer Vibes",
        "tags": "pop, summer, upbeat",
        "prompt": "[Verse 1]\nGolden sunlight spreads across the sand...",
        "model_name": "chirp-hawk",
        "duration": 121.0
      }
    ]
  }
}

Lyrics generation result:

code

{
  "code": "success",
  "data": {
    "status": "SUCCESS",
    "fail_reason": null,
    "data": [
      {
        "id": "lyrics_ghi789",
        "title": "Rise Up",
        "text": "[Verse 1]\nWhen storms crash against the shore\nWhen your heart still waits for more..."
      }
    ]
  }
}

Failed:

code

{
  "code": "success",
  "data": {
    "status": "FAILED",
    "fail_reason": "Content policy violation",
    "data": []
  }
}

Song Data Field Structure

Field	Type	Description
`id` / `clip_id`	string	Music clip ID
`audio_url`	string	MP3 file URL for playback or download
`video_url`	string	MP4 file URL (video with music)
`image_url`	string	Song thumbnail image URL
`title`	string	Song title
`tags`	string	Music genre
`prompt`	string	Generated lyrics
`model_name`	string	Model used
`duration`	number	Duration in seconds

Task Statuses

Status	Meaning
`SUBMITTED`	Submitted, waiting in queue
`QUEUEING`	Queued for processing
`PROCESSING`	Generating music/lyrics
`SUCCESS`	Completed, results available
`FAILED`	Failed, see `fail_reason`

Supported Models

Notice: As of 2026-09-09, all legacy Suno models have been retired. Any request whose mv is not one of the three V6 values below (chirp-hawk, chirp-hawk-wild, chirp-goose) is automatically forwarded to chirp-hawk (V6 base).

`mv` Value	Version	Released	`prompt` limit	`tags` limit	Max duration
`chirp-hawk`	V6	2026-09-09	5,000 chars	1,000 chars	8 minutes
`chirp-hawk-wild`	V6 wild	2026-09-09	5,000 chars	1,000 chars	8 minutes
`chirp-goose`	V6 mini	2026-09-09	5,000 chars	1,000 chars	8 minutes

Legacy models

The mv values below are still accepted, but the underlying models have been retired. Requests using them are automatically forwarded to chirp-hawk, and the model_name field in the result reflects the V6 model that actually ran, not the value you sent.

`mv` Value	Original version
`chirp-v3.0`	v3.0
`chirp-v3.5`	v3.5
`chirp-v4`	v4.0
`chirp-auk`	v4.5
`chirp-bluejay`	v4.5+
`chirp-crow`	v5.0
`chirp-fenix`	v5.5

Error Handling

code

{
  "code": "error",
  "message": "Invalid API key"
}

HTTP Code	Cause
`401`	Missing or invalid API key
`400`	Request body missing required parameters
`500`	Server or upstream error

Best Practices

Poll reasonably: Call /suno/fetch/{taskId} every 3 seconds; avoid continuous polling to prevent rate limiting.
Timeout: If a task hasn't completed after 5 minutes, consider abandoning it and trying again.
Handle 2 tracks: Each music generation request returns 2 clips — let users pick their favorite.
Clear prompts: Describe genre, emotion, and tempo in detail for better AI-generated results.
Tags: Use tags to guide the genre: pop, rock, jazz, electronic, classical, hip-hop...

In this section · Multimedia

Video Generation (Veo & Grok)

Nano Banana

Text-to-Speech (TTS)

PreviousText-to-Speech (TTS)Next DNS Resolver