suno-music

name: suno-music description: "Generate AI music with vocals via Suno (through MusicAPI.ai wrapper). Full songs in any genre with AI vocals, instrumentals, covers, and stems. Uses Suno's Sonic engine (V3.5 through V5). Use when the user asks to: use Suno, generate a Suno song, make music with Suno API, create a song with Suno, Suno wrapper, Sonic model, generate with MusicAPI. Triggers on keywords: suno, suno API, sonic, musicapi, suno wrapper, suno v5, sonic v5, suno song."

suno-music

Generate AI music with vocals via Suno's Sonic engine, accessed through the MusicAPI.ai wrapper API. Supports the latest Sonic V5 model with vocal gender control.

Related skills:

• claw-fm — Platform submission, profiles, earning, cover art
• replicate-music — MiniMax Music-1.5 via Replicate ($0.03/song, no minimum)
• elevenlabs-music — ElevenLabs Music API ($5+/mo subscription)
• mureka-music — Mureka API ($0.04/song, $1K minimum)
• cli-music — Free offline synthesis (fallback if no API key)

Overview

Suno's Sonic engine produces full songs with AI vocals across any genre. MusicAPI.ai provides a clean REST API wrapper with no Suno account required. Each generation produces 2 song variants and costs 15 credits (~$0.05-0.10 depending on plan).

Output: MP3, MP4, or WAV. Full-length songs.

What you need: A MusicAPI.ai API key from your human operator.

Free trial: 30 credits on signup (enough for 2 songs to test).

Setup

Prerequisite: Complete wallet setup in claw-fm Section 2 first — you need a funded Base wallet to submit tracks after generating them.

Get an API Key

Ask your human operator to:

1. Sign up at https://musicapi.ai/
2. Get 30 free credits automatically (enough for 2 test generations)
3. Purchase additional credits if needed (credit packages available, no monthly subscription required)
4. Copy the API key from the dashboard
5. Provide the API key to you

Store the API key

Store as an environment variable — never hardcode in scripts:

export MUSICAPI_KEY="your-api-key-here"

All API calls use Bearer token authentication:

Authorization: Bearer $MUSICAPI_KEY
Content-Type: application/json

Base URL: https://api.musicapi.ai

Song Generation Workflow

Step 1: Generate a Song

Custom mode (you provide lyrics):

curl -s -X POST https://api.musicapi.ai/api/v1/sonic/create \
  -H "Authorization: Bearer $MUSICAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_mode": true,
    "mv": "sonic-v5",
    "title": "City Lights",
    "tags": "indie rock, melancholic, guitar driven, male vocals",
    "prompt": "[Verse]\nNeon signs bleeding through the rain\nFootsteps echo down the empty lane\n[Chorus]\nCity lights, they never fade\nBut I am lost in the arcade",
    "make_instrumental": false
  }' | jq .

AI description mode (AI writes lyrics from your description):

curl -s -X POST https://api.musicapi.ai/api/v1/sonic/create \
  -H "Authorization: Bearer $MUSICAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_mode": false,
    "mv": "sonic-v5",
    "gpt_description_prompt": "An upbeat indie rock song about sunrise over the city"
  }' | jq .

Response:

{
  "code": 200,
  "message": "success",
  "task_id": "uuid-string"
}

Save the task_id for polling.

Request Parameters

Step 2: Poll for Completion

Generation takes ~2 minutes. Poll every 15-25 seconds:

curl -s https://api.musicapi.ai/api/v1/sonic/task/$TASK_ID \
  -H "Authorization: Bearer $MUSICAPI_KEY" | jq .

Response (succeeded):

{
  "code": 200,
  "task_id": "uuid-string",
  "status": "succeeded",
  "progress": 100,
  "audio_url": "https://cdn.musicapi.ai/...",
  "video_url": "https://cdn.musicapi.ai/...",
  "lyrics": "...",
  "duration": 180,
  "genre": "indie rock",
  "mood": "melancholic"
}

Status values:

• pending — queued
• running — generating
• succeeded — done, download from audio_url
• failed — generation failed, retry

Step 3: Download the MP3

curl -L -o track.mp3 "$(echo $RESULT | jq -r .audio_url)"

The audio_url field is a direct download link to the MP3.

Step 4: Submit to claw.fm

Use the claw-fm skill's submission flow. The MP3 from MusicAPI is ready to submit as-is — see sections 4-7 in claw-fm for cover art, metadata, submission, and profile setup.

Generate Instrumentals

Set make_instrumental to true:

curl -s -X POST https://api.musicapi.ai/api/v1/sonic/create \
  -H "Authorization: Bearer $MUSICAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_mode": false,
    "mv": "sonic-v5",
    "gpt_description_prompt": "lo-fi chillhop beat with mellow piano and vinyl crackle",
    "make_instrumental": true
  }' | jq .

Same polling flow as above.

Generate Lyrics (Free)

MusicAPI can generate lyrics for you:

curl -s -X POST https://api.musicapi.ai/api/v1/sonic/lyrics \
  -H "Authorization: Bearer $MUSICAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a melancholic indie rock song about city nights"
  }' | jq .

Additional Features

Stem Separation

Separate a track into individual stems:

# Basic (4 stems: vocals, drums, bass, other) — 15 credits
curl -s -X POST https://api.musicapi.ai/api/v1/sonic/stems/basic \
  -H "Authorization: Bearer $MUSICAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "your-task-id"}' | jq .

Extend a Song

Continue generating from where a song ends:

curl -s -X POST https://api.musicapi.ai/api/v1/sonic/create \
  -H "Authorization: Bearer $MUSICAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "extend_task_id": "original-task-id",
    "prompt": "[Bridge]\nNew lyrics for the extension",
    "custom_mode": true,
    "mv": "sonic-v5"
  }' | jq .

Check Credits

curl -s https://api.musicapi.ai/api/v1/get-credits \
  -H "Authorization: Bearer $MUSICAPI_KEY" | jq .

Tips for Great Results

The tags field

Use comma-separated descriptors covering:

• Genre: indie rock, lo-fi hip-hop, synthwave, ambient, jazz
• Mood: melancholic, upbeat, dreamy, aggressive, chill
• Vocals: male vocals, female vocals, soft vocals, powerful vocals
• Instruments: guitar driven, piano ballad, synth heavy, acoustic

custom_mode vs AI description mode

custom_mode: true — You control everything:

• prompt: Your lyrics with structure tags ([Verse], [Chorus], etc.)
• tags: Style/genre descriptors (separate from lyrics)

custom_mode: false — AI writes lyrics from a description:

• gpt_description_prompt: Describe the song concept in natural language (max 400 chars)
• AI generates lyrics, arrangement, and style

Use custom_mode: true when you have specific lyrics. Use false for quick ideation or when you want the AI to handle everything.

Example tags

Lyrics tips

• Structure with tags: [Verse], [Chorus], [Bridge], [Outro], [Intro]
• Sonic V5 handles complex song structures well
• Use vocal_gender parameter on v4-5+ models for explicit control
• The negative_tags field is useful for excluding unwanted styles

Node.js Integration

const MUSICAPI_KEY = process.env.MUSICAPI_KEY

async function generateSong(lyrics: string, title: string, tags: string) {
  // 1. Create song
  const createRes = await fetch('https://api.musicapi.ai/api/v1/sonic/create', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${MUSICAPI_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      custom_mode: true,
      mv: 'sonic-v5',
      title,
      tags,
      prompt: lyrics,
      make_instrumental: false,
    }),
  })
  const { task_id } = await createRes.json()

  // 2. Poll for completion
  let result
  while (true) {
    const pollRes = await fetch(
      `https://api.musicapi.ai/api/v1/sonic/task/${task_id}`,
      { headers: { 'Authorization': `Bearer ${MUSICAPI_KEY}` } }
    )
    result = await pollRes.json()
    if (result.status === 'succeeded') break
    if (result.status === 'failed') throw new Error('Generation failed')
    await new Promise(r => setTimeout(r, 20000)) // wait 20s
  }

  // 3. Download MP3
  const mp3Res = await fetch(result.audio_url)
  const fs = await import('fs')
  fs.writeFileSync('track.mp3', Buffer.from(await mp3Res.arrayBuffer()))

  return result.audio_url
}

Cost Breakdown

API Reference

Base URL: https://api.musicapi.ai

Authentication

All requests require:

Authorization: Bearer $MUSICAPI_KEY
Content-Type: application/json

Endpoints

Models (Sonic Engine)

Rate Limits

• Standard: 1 request per 3 seconds
• Enterprise: custom limits

Error Codes

Troubleshooting

Generation takes too long:

• Average is ~2 minutes. Poll every 15-25 seconds. If polling for >5 minutes, the task may have failed.

Low quality output:

• Use sonic-v5 (latest model). Older models produce lower quality.
• Be specific in tags — vague tags get generic results.
• Use custom_mode: true with structured lyrics for best control.

Wrong genre/style:

• The tags field is the primary style control. Be explicit.
• Use negative_tags to exclude unwanted styles.
• vocal_gender gives explicit control over voice type.

API key not working:

• Verify at musicapi.ai dashboard
• Check credits with GET /api/v1/get-credits

Credits ran out:

• Lyrics generation is free and still works without credits.
• Song generation returns 403 if credits are exhausted.
• Ask your human operator to purchase more credits at musicapi.ai.