Suno

AI music generation powered by Suno. Generate high-quality songs with lyrics, instrumentals, and custom styles. Each generation produces multiple audio tracks.

Models

Model Name	Description
`suno-v5_5`	Suno V5.5 - Tailored custom models for personalized taste
`suno-v5`	Suno V5 - Superior expression, faster generation

Pricing

Flat rate per generation:

Model	Credits	Price
`suno-v5_5`	24 credits	$0.12
`suno-v5`	24 credits	$0.12

Each generation produces multiple audio tracks.

Create Task

curl -X POST https://api.aivideoapi.ai/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5_5",
    "input": {
      "prompt": "A calm and relaxing piano track with soft melodies",
      "custom_mode": false,
      "instrumental": true
    }
  }'

Request Body

Field	Type	Required	Description
`model`	string	Yes	`suno-v5_5` or `suno-v5`
`input`	object	Yes	Generation parameters, see below
`callback_url`	string	No	URL to receive task completion/failure notifications

Input Object

The input parameters depend on whether custom mode is enabled.

Non-Custom Mode (Simple)

Field	Type	Required	Description
`prompt`	string	Yes	Audio content description (max 500 characters)
`custom_mode`	boolean	No	Set to `false` or omit. Default `false`
`instrumental`	boolean	No	Generate without vocals if `true`. Default `false`

Custom Mode

Field	Type	Required	Description
`prompt`	string	Conditional	Lyrics text (max 3000 characters). Required when `instrumental` is `false`
`custom_mode`	boolean	Yes	Must be `true`
`instrumental`	boolean	No	Generate without vocals if `true`. Default `false`
`title`	string	Yes	Track title (max 80 characters)
`style`	string	Yes	Genre/mood specification (max 200 characters)
`negative_tags`	string	No	Styles to exclude (max 200 characters)
`vocal_gender`	string	No	Vocal preference: `m` (male) or `f` (female)
`persona_id`	string	No	Custom persona style ID
`style_weight`	number	No	Style adherence strength (0-1)
`weirdness_constraint`	number	No	Creative deviation control (0-1)
`audio_weight`	number	No	Audio feature balance (0-1)

Example: Simple Generation

curl -X POST https://api.aivideoapi.ai/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5",
    "input": {
      "prompt": "An upbeat electronic dance track with heavy bass drops"
    }
  }'

Example: Custom Instrumental

curl -X POST https://api.aivideoapi.ai/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5_5",
    "input": {
      "custom_mode": true,
      "instrumental": true,
      "title": "Peaceful Piano Meditation",
      "style": "Classical, Ambient, Piano",
      "negative_tags": "Heavy Metal, Drums"
    }
  }'

Example: Custom Song with Lyrics

curl -X POST https://api.aivideoapi.ai/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v5_5",
    "callback_url": "https://your-server.com/webhook",
    "input": {
      "custom_mode": true,
      "instrumental": false,
      "title": "Summer Nights",
      "style": "Pop, Indie",
      "vocal_gender": "f",
      "prompt": "[Verse]\nWalking down the empty street\nCity lights beneath my feet\nEvery star is shining bright\nLost inside the summer night\n\n[Chorus]\nSummer nights, we come alive\nDancing under neon skies"
    }
  }'

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Query Task

curl https://api.aivideoapi.ai/v1/tasks/{taskId} \
  -H "Authorization: Bearer sk-your-api-key"

Status transitions: pending -> processing -> completed or failed.

Completed

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "model": "suno-v5_5",
  "created_at": 1775383908,
  "completed_at": 1775384028,
  "output": {
    "urls": [
      "https://file.aivideoapi.ai/audio/2026/04/05/track1.mp3",
      "https://file.aivideoapi.ai/audio/2026/04/05/track2.mp3"
    ],
    "metadata": {
      "tracks": [
        {
          "id": "track-uuid-1",
          "title": "Summer Nights",
          "tags": "pop, indie",
          "duration": 198.44,
          "image_url": "https://example.com/cover1.jpeg",
          "prompt": "[Verse]\nWalking down the empty street..."
        },
        {
          "id": "track-uuid-2",
          "title": "Summer Nights",
          "tags": "pop, indie",
          "duration": 201.12,
          "image_url": "https://example.com/cover2.jpeg",
          "prompt": "[Verse]\nWalking down the empty street..."
        }
      ]
    }
  }
}

Audio URLs are valid for 24 hours. Each generation typically produces 2 track variations.

Failed

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "model": "suno-v5_5",
  "created_at": 1775383908,
  "error": {
    "code": "upstream_error",
    "message": "Music generation failed"
  }
}

When a task fails, pre-charged credits are automatically refunded.

Callback

Pass callback_url when creating the task. The system will automatically send a POST request to your URL when the task completes or fails. The format matches the query task response.

Error Codes

When a request fails, the API returns a JSON error response:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your credit balance is too low. Please top up.",
    "type": "billing_error"
  }
}

Error Reference

HTTP Status	Code	Type	Description
400	`invalid_request`	invalid_request_error	Missing or invalid parameters
401	`invalid_api_key`	authentication_error	API key is invalid, disabled, or deleted
402	`insufficient_credits`	billing_error	Credit balance too low, please top up
403	`ip_not_allowed`	permission_error	Request IP not in the key's allowlist
404	`model_not_found`	invalid_request_error	Model does not exist or is inactive
404	`task_not_found`	invalid_request_error	Task ID does not exist
429	`rate_limit_exceeded`	rate_limit_error	Too many requests, please slow down
429	`spend_limit_exceeded`	billing_error	Key spend limit reached (hourly/daily/total)
500	`internal_error`	api_error	Unexpected server error
503	`upstream_error`	upstream_error	Upstream AI provider returned an error

Common Scenarios

invalid_request (400)

Returned when required fields are missing or invalid.

{
  "error": {
    "code": "invalid_request",
    "message": "'model' is required.",
    "type": "invalid_request_error"
  }
}

insufficient_credits (402)

Your balance is too low. Check your balance with GET /v1/credits and top up in Dashboard > Billing.

invalid_api_key (401)

Possible causes:

The key does not start with sk-
The key has been disabled or deleted
The user account has been banned

upstream_error (503)

The upstream AI provider returned an error. This may happen when:

The input contains sensitive or prohibited content
The provider is temporarily unavailable
The request parameters are not supported by the provider

Credits are automatically refunded when a task fails due to upstream errors.