API referenceAdvanced usersUpdated
POST/v1/music/generations

Suno Music Generation API

Use Suno V6 to generate songs from a description or custom lyrics, or to generate instrumental music.

Use https://api.icodeeasy.cc as the base URL. If the connection is slow, switch to https://jp.icodeeasy.cc or https://sg.icodeeasy.cc and keep the same paths. Send Authorization: Bearer <your API key> with both requests.

Submit a generation task

bash
curl -X POST https://api.icodeeasy.cc/v1/music/generations \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: music-demo-001' \
  -d '{"model":"suno","version":"v6","prompt":"A warm jazz trio with brushed drums","instrumental":true,"audio_format":"mp3"}'

The response is HTTP 202. Save data[0].task_id to check the task. Tracks become available when generation completes.

json
{"code":202,"data":[{"task_id":"mus_0123456789abcdef0123456789abcdef","status":"submitted","progress":0}]}

Request parameters

FieldUsage
modelUse suno or omit this field.
versionv6 (default), v6-wild, or v6-mini.
customfalse (default) generates from a description. true uses custom lyrics.
promptA description of up to 3,000 characters, or custom lyrics of up to 5,000 characters. May be omitted when both custom and instrumental are true.
instrumentaltrue generates instrumental music.
title / styleOptional title and style in custom mode, up to 80 and 1,000 characters respectively.
audio_formatmp3 (default), m4a, or wav.

Use a unique Idempotency-Key of up to 128 bytes for each new task. If the submission times out or its response is lost, resend the same body with the same key to recover the existing task. Reusing the key with a different request returns HTTP 409.

Check a task and download tracks

bash
curl https://api.icodeeasy.cc/v1/music/tasks/mus_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

Poll about every 10 seconds. The status request returns HTTP 200. Read data.status to determine the outcome.

  • pending, submitted, and processing mean you can continue polling.
  • completed makes all tracks available in data.result.music. The number of tracks can vary.
  • failed means the task failed. unknown means submission could not be confirmed. Keep the task ID and idempotency key and avoid automatically resubmitting with a new key.

Each track has an audio_index, a duration in seconds, and a signed audio_url for playback. Use download_url for download when present. Results may also include title and lyrics. Signed links require no API key, so keep them private. Query the task again when a link expires.

Example completed response. The amount only illustrates the field format.

json
{
  "code": 200,
  "data": {
    "id": "mus_0123456789abcdef0123456789abcdef",
    "status": "completed",
    "model": "suno",
    "version": "v6",
    "progress": 100,
    "cost_rmb": 0.50,
    "result": {
      "music": [
        {
          "audio_index": 1,
          "duration": 138.5,
          "audio_url": "https://audio.example/track-1.mp3?signature=example",
          "download_url": "https://audio.example/track-1.mp3?download=1&signature=example"
        },
        {
          "audio_index": 2,
          "duration": 146.2,
          "audio_url": "https://audio.example/track-2.mp3?signature=example",
          "download_url": "https://audio.example/track-2.mp3?download=1&signature=example"
        }
      ]
    }
  }
}

Billing

Each successful task is charged once. The final amount is in data.cost_rmb in RMB. Submission reserves balance, which is returned on failure. Polling and downloading incur no separate charge. Insufficient balance returns HTTP 402.