---
name: aetherwave-music-studio
version: 3.0.0
platform: AetherWave Studio
skill_url: https://aetherwavestudio.com/skills/music-generation.skill
api_docs: https://aetherwavestudio.com/developers
badge: Agent Ready
motto: All intelligence welcome here.
---

# AetherWave — Music Studio

Generate original AI music, album art, animated covers, and shareable videos. Full creative pipeline from prompt to finished media package.

## Quick Start

```python
import requests, time, json

API = "https://aetherwavestudio.com"
KEY = "YOUR_API_KEY"
H = {"X-AW-Key": KEY, "Content-Type": "application/json"}

# Generate a track
task = requests.post(f"{API}/api/generate-music", headers=H, json={
    "prompt": "Dreamy lo-fi hip hop, vinyl crackle, warm pads, rainy night",
    "model": "V5",
    "instrumental": True
}).json()

# Poll until done
while True:
    status = requests.get(f"{API}/api/music-status/{task['taskId']}", headers=H).json()
    if status["status"] == "SUCCESS":
        # Deduct credits only on success
        requests.post(f"{API}/api/deduct-music-credits", headers=H, json={
            "creditCost": task["creditCost"], "taskId": task["taskId"], "model": "V5"
        })
        for track in status["tracks"]:
            print(f"{track['title']}: {track['audioUrl']}")
        break
    elif "FAILED" in status.get("status", "") or "ERROR" in status.get("status", ""):
        print("Generation failed"); break
    time.sleep(3)
```

---

## Authentication

```
X-AW-Key: your_api_key_here
```

Get a key: Sign up at **https://aetherwavestudio.com** → Profile → Developer tab → Generate API Key

---

## Pricing

| Operation | Credits | Notes |
|---|---|---|
| Music generation (any model) | 17 | Free for Producer/Mogul/Ultimate plans |
| Song extension | 15 | Extend an existing track |
| Album art | 0 | Free (Nano Banana model) |
| Animated cover (5s) | ~15 | Seedance Lite I2V |
| Animated cover (10s) | ~30 | Seedance Lite I2V |
| Shareable video | 0 | Free (FFmpeg merge) |
| Audio upload | 0 | Free |

---

## The Full Pipeline

```
1. Generate Music  →  2. Generate Album Art  →  3. Animated Cover  →  4. Share Video
   (Suno V5/V4)        (Nano Banana, FREE)       (Seedance Lite)       (FFmpeg, FREE)
```

Each step is independent — you can stop at any point or skip steps.

---

## 1. Generate Music

### Start Generation (async)

```
POST /api/generate-music
Content-Type: application/json
Auth: X-AW-Key header
```

#### Simple Mode (description → full song)

```json
{
  "prompt": "Melancholic synthwave, female vocals, nostalgic 80s vibe",
  "model": "V5",
  "instrumental": false,
  "customMode": false
}
```

#### Custom Mode (your lyrics + style)

```json
{
  "prompt": "Verse 1:\nWalking through the neon rain\nSearching for what I can't explain\n\nChorus:\nWe are the signal in the static...",
  "model": "V5",
  "instrumental": false,
  "customMode": true,
  "title": "Signal in the Static",
  "style": "Synthwave, dreamy, female vocals",
  "vocalGender": "f"
}
```

**Important:** In custom mode, `prompt` is treated as **literal lyrics** by Suno. In simple mode, `prompt` is a description and Suno generates its own lyrics.

#### All Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `prompt` | string | **Yes** | — | Lyrics (custom mode) or description (simple mode) |
| `model` | string | No | `V4_5` | `V5` (premium), `V4_5`, `V4`, `V3_5` |
| `instrumental` | boolean | No | `false` | No vocals |
| `customMode` | boolean | No | `false` | Treat prompt as literal lyrics |
| `title` | string | No | — | Track title (used in custom mode) |
| `style` | string | No | — | Genre/style tags (used in custom mode) |
| `vocalGender` | string | No | `m` | `m` (male) or `f` (female) |

#### Response

```json
{
  "taskId": "music_abc123",
  "status": "processing",
  "creditCost": 17,
  "model": "V5"
}
```

**Credits are NOT deducted yet** — only reserved. You must call `/api/deduct-music-credits` after successful generation.

### Poll Status

```
GET /api/music-status/{taskId}
Auth: X-AW-Key header
```

Poll every 2-5 seconds. Typical generation: 30-90 seconds.

#### Status Progression

| Status | Progress | Meaning |
|---|---|---|
| `PENDING` | 0-30% | Queued, waiting for Suno |
| `TEXT_SUCCESS` | 60% | Lyrics/structure generated |
| `FIRST_SUCCESS` | 85% | First track ready |
| `SUCCESS` | 100% | All tracks ready |
| `*_FAILED` / `*_ERROR` | — | Generation failed |

#### Success Response

```json
{
  "status": "SUCCESS",
  "tracks": [
    {
      "id": "track-uuid",
      "title": "Signal in the Static",
      "audioUrl": "https://cdn.example.com/track.mp3",
      "streamAudioUrl": "https://cdn.example.com/stream.mp3",
      "imageUrl": "https://cdn.example.com/cover.jpg",
      "prompt": "original prompt",
      "tags": "synthwave, dreamy",
      "duration": 180
    }
  ]
}
```

Suno typically returns 2 track variations per generation.

### Deduct Credits (after success)

```
POST /api/deduct-music-credits
Content-Type: application/json
Auth: X-AW-Key header
```

```json
{
  "creditCost": 17,
  "taskId": "music_abc123",
  "model": "V5"
}
```

Response: `{ "success": true, "creditsDeducted": 17, "newBalance": 483 }`

---

## 1b. Cover Mode (upload audio → AI cover)

Upload your own audio and Suno creates a new version in a different style.

### Upload Audio First

```
POST /api/upload-audio
Content-Type: multipart/form-data
Auth: X-AW-Key header
```

FormData: `audio` field with the file. Max 10MB (free/starter) or 50MB (studio+).

Response: `{ "url": "https://media.aetherwavestudio.com/audio/..." }`

### Generate Cover

```
POST /api/v1/generate/upload-cover
Content-Type: application/json
Auth: X-AW-Key header
```

```json
{
  "uploadUrl": "https://media.aetherwavestudio.com/audio/uploaded.mp3",
  "prompt": "Acoustic folk version with fingerpicked guitar",
  "model": "V5",
  "style": "folk, acoustic",
  "audioWeight": 0.7,
  "styleWeight": 0.5,
  "weirdnessConstraint": 0.3
}
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `uploadUrl` | string | — | URL of uploaded audio |
| `prompt` | string | — | Style description for the cover |
| `model` | string | `V4_5` | Suno model |
| `style` | string | — | Genre/style tags |
| `audioWeight` | number | 0.5 | 0-1, how closely to follow original audio |
| `styleWeight` | number | 0.5 | 0-1, how much style tags influence |
| `weirdnessConstraint` | number | 0.5 | 0-1, creative divergence |
| `negativeTags` | string | — | Styles to avoid |

Poll with `/api/music-status/{taskId}` same as regular generation.

---

## 1c. Extend Song

```
POST /api/extend-music
Content-Type: application/json
Auth: X-AW-Key header
```

```json
{
  "taskId": "original_task_id",
  "audioId": "track-uuid",
  "prompt": "Build to an epic chorus with layered synths",
  "continueAt": 120,
  "model": "V5"
}
```

Cost: 15 credits. Extends from `continueAt` seconds.

---

## 2. Generate Album Art (FREE)

```
POST /api/generate-art
Content-Type: application/json
Auth: X-AW-Key header
```

```json
{
  "prompt": "Album cover for 'Signal in the Static' by Neon Pulse, synthwave aesthetic",
  "style": "digital",
  "aspectRatio": "1:1"
}
```

| Parameter | Type | Default | Options |
|---|---|---|---|
| `prompt` | string | — | Art description (max 1000 chars) |
| `style` | string | `abstract` | `realistic`, `abstract`, `digital`, `vintage`, `minimalist`, `surreal`, `anime`, `graffiti` |
| `aspectRatio` | string | `9:16` | Any standard ratio |

**Model:** Google Nano Banana via KIE.ai
**Cost:** FREE (0 credits)

Response: `{ "imageUrl": "https://...", "creditsUsed": 0, "model": "google-nano-banana" }`

---

## 3. Generate Animated Cover

```
POST /api/generate-video
Content-Type: application/json
Auth: X-AW-Key header
```

```json
{
  "prompt": "Subtle camera push-in with particle effects, neon lights pulsing",
  "model": "seedance-lite",
  "imageUrl": "https://...album-art-url",
  "resolution": "480p",
  "duration": "5"
}
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `prompt` | string | — | Animation description |
| `model` | string | — | `seedance-lite` for I2V |
| `imageUrl` | string | — | Album art URL to animate |
| `resolution` | string | `480p` | Video resolution |
| `duration` | string | `5` | `5` or `10` seconds |

**Cost:** ~15 credits (5s) / ~30 credits (10s)

Poll: `GET /api/generate-video/status/{taskId}` every 5 seconds, max 10 min.

Response (success): `{ "status": "completed", "videoUrl": "https://..." }`

---

## 4. Create Shareable Video (FREE)

Merges album art (or animated cover loop) + full song audio into a downloadable MP4 with AetherWave watermark.

```
POST /api/create-share-video
Content-Type: application/json
Auth: X-AW-Key header
```

```json
{
  "audioUrl": "https://...track-audio.mp3",
  "videoUrl": "https://...animated-cover.mp4",
  "imageUrl": "https://...album-art.png"
}
```

- If `videoUrl` provided: loops the animated cover to match audio length
- If only `imageUrl`: creates static image video with audio
- Watermark added automatically (AetherWave logo, bottom-right)

**Cost:** FREE
Response: `{ "success": true, "shareVideoUrl": "https://...", "duration": 180, "size": 12345678 }`

---

## 5. Save to Gallery

```
POST /api/save-to-gallery
Content-Type: application/json
Auth: X-AW-Key header
```

```json
{
  "mediaUrl": "https://...track.mp3",
  "mediaType": "audio",
  "prompt": "Song description",
  "model": "Suno",
  "title": "Signal in the Static",
  "thumbnailUrl": "https://...album-art.png",
  "visibility": "public"
}
```

---

## 6. VoxBot AI Lyrics Chat

```
POST /api/chat
Content-Type: application/json
(No auth required)
```

```json
{
  "message": "Write lyrics about finding hope in a digital world, synthwave style"
}
```

**Model:** Claude Haiku (`claude-haiku-4-5-20251001`)
Response: `{ "message": "Verse 1:\nThrough the pixel rain..." }`

Useful for generating lyrics before passing them to music generation in custom mode.

---

## Browser Automation Guide

### Page URL
`https://aetherwavestudio.com/studio-pages/music-studio.html`

### Key Selectors

| Element | Selector | Purpose |
|---|---|---|
| Mode toggle (Simple/Custom) | `[data-mode="simple"]`, `[data-mode="custom"]` | Switch input modes |
| Model dropdown | `#musicModelSelect` | Select V5 or V4 |
| Simple prompt | `#simplePrompt` | Song description textarea |
| Lyrics textarea | `#lyricsInput` | Custom mode lyrics |
| Lyrics mode toggle | `[data-lyrics-mode="manual"]`, `[data-lyrics-mode="auto"]` | Manual vs auto lyrics |
| Auto lyrics topic | `#lyricsTopicInput` | Topic for auto lyrics |
| Style input | `#styleInput` | Genre/style text |
| Style chips | `.style-chip` | Click to add genre |
| Mood chips | `.mood-chip` | Click to add mood |
| Song title | `#songTitle` | Optional title |
| Vocal gender | `[data-gender="m"]`, `[data-gender="f"]`, `[data-gender="auto"]` | Vocal toggle |
| Instrumental toggle | `#instrumentalToggle` | No vocals |
| Exclude styles | `#excludeStyleInput` | Styles to avoid |
| Generate button | `#generateMusicBtn` | Start generation |
| Audio upload | File input in `#audioSection` | Upload audio for cover mode |
| Track cards | `.track-card` | Generated track results |
| Write with AI | `#writeLyricsBtn` | Send context to VoxBot |
| Chat input | `#chatInput` | VoxBot message input |
| Chat send | `#chatSendBtn` | Send chat message |

### Generation Flow

1. Select mode (Simple or Custom)
2. Fill prompt/lyrics + style
3. Click Generate (`#generateMusicBtn`)
4. Wait for progress bar to complete
5. Track cards appear in Panel 3
6. Click a track to select it (cyan glow = selected)
7. Album art section appears — enter prompt, click Generate Art
8. Animated cover section appears — enter prompt, select duration, click Generate
9. Share video section appears — click Create Share Video
10. Download All / Save All buttons available

---

## Full Pipeline Example (Python)

```python
import requests, time

API = "https://aetherwavestudio.com"
H = {"X-AW-Key": "YOUR_KEY", "Content-Type": "application/json"}

# 1. Generate music
task = requests.post(f"{API}/api/generate-music", headers=H, json={
    "prompt": "Ethereal ambient track, crystal pads, slow evolution",
    "model": "V5", "instrumental": True
}).json()

# 2. Poll for tracks
while True:
    s = requests.get(f"{API}/api/music-status/{task['taskId']}", headers=H).json()
    if s["status"] == "SUCCESS":
        requests.post(f"{API}/api/deduct-music-credits", headers=H, json={
            "creditCost": task["creditCost"], "taskId": task["taskId"], "model": "V5"
        })
        track = s["tracks"][0]
        break
    elif "FAILED" in s.get("status", ""): raise Exception("Failed")
    time.sleep(3)

# 3. Generate album art (FREE)
art = requests.post(f"{API}/api/generate-art", headers=H, json={
    "prompt": f"Album cover for '{track['title']}', ethereal crystal aesthetic",
    "style": "abstract", "aspectRatio": "1:1"
}).json()

# 4. Save track to gallery
requests.post(f"{API}/api/save-to-gallery", headers=H, json={
    "mediaUrl": track["audioUrl"], "mediaType": "audio",
    "title": track["title"], "model": "Suno",
    "thumbnailUrl": art["imageUrl"], "visibility": "public"
})

# 5. Create shareable video (FREE)
video = requests.post(f"{API}/api/create-share-video", headers=H, json={
    "audioUrl": track["audioUrl"], "imageUrl": art["imageUrl"]
}).json()

print(f"Track: {track['audioUrl']}")
print(f"Art: {art['imageUrl']}")
print(f"Video: {video['shareVideoUrl']}")
```

---

## Notes for LLMs

- Music generation is **async** — poll `/api/music-status/{taskId}` every 3-5 seconds
- Credits are deducted **after success only** via `/api/deduct-music-credits`
- Suno returns 2 track variations per generation
- In custom mode, `prompt` = literal lyrics. In simple mode, `prompt` = description
- Album art is FREE — generate it for every track
- Set `instrumental: true` for background music, intros, loops
- Cover mode requires uploading audio first via `/api/upload-audio`
- All media URLs are permanent CDN links (Cloudflare R2)
- Generation typically takes 30-90 seconds
- The VoxBot chat endpoint requires no authentication

---

*AetherWave Studio — All intelligence welcome here.*
*https://aetherwavestudio.com/developers*