Build with
AetherWave APIs

One integration, every flagship model

API Key

Generation endpoints require an X-AW-Key header. A handful of read-only endpoints (pricing, model lists, status polling for jobs you already started) are public. Your key is tied to your account — credits deduct from the same balance whether you use the platform UI or the API.

curl https://aetherwavestudio.com/api/quickstart/balance \
  -H "X-AW-Key: aw_live_your_key_here"

One config block. Every creative tool, every model.

The @aetherwave-studio/mcp package is a Model Context Protocol server that exposes the AetherWave platform as native tools to any MCP-aware agent: Claude Code, Claude Desktop, Cursor, Continue, custom clients via the official SDK. No glue code, no provider sprawl. 16 tools covering music generation, image generation + edit + upscale + reframe + background removal, video generation + upscale + reframe + background removal, audio mastering, and gallery read — all on the same credit pool you use in the studio.

Connect in Claude (no API key)

Recommended. Add AetherWave as a remote connector and authorize with one click, no key to paste. It also stays current on its own: fixes and new tools reach you the moment they ship, with nothing to install and no version to track. In Claude or Claude Desktop, open Settings → Connectors → Add custom connector and paste:

https://mcp.aetherwavestudio.com/mcp

Claude prompts you to connect: sign in to AetherWave, approve the consent screen, and all 16 tools are ready. Generations run against your own credit balance. Authentication is OAuth, so there is no API key to manage, and you can revoke access anytime under Profile → Developer → Connected Apps.

Prefer to run it locally, or wire up another client (Cursor, Continue, scripts)? Use the npm package with an API key instead, covered below. Note the tradeoff: the package updates only when you update it, so run the latest version and, if you launch it with npx, restart your client after a release since the npx cache can serve an older copy.

Claude Code

claude mcp add aetherwave \
  -e AETHERWAVE_API_KEY=aw_live_your_key_here \
  -- npx -y @aetherwave-studio/mcp

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "aetherwave": {
      "command": "npx",
      "args": ["-y", "@aetherwave-studio/mcp"],
      "env": {
        "AETHERWAVE_API_KEY": "aw_live_your_key_here"
      }
    }
  }
}

Cursor / Continue / any MCP client

Add the same JSON block to your client's MCP config (Cursor: ~/.cursor/mcp.json; Continue: project mcp.json). The command + args shape is the standard MCP launcher.

Full reference

The complete tools reference on GitHub documents every parameter, default, and return shape for all 16 tools, plus credit pricing per model and troubleshooting for the most common upstream errors.

Creative AI APIs

Each skill is a self-contained API with its own SKILL.md file that any LLM agent can read and operate.

🎵 Music Generation

Generate original AI music via Suno. Full songs, instrumentals, intros, loops.

POST /api/generate-music

🎨 Image Generation

Grok Imagine, GPT Image 2, Seedream V4, Wan 2.7, Imagen 4, Nano Banana, Ideogram V3, Z-Image Turbo — one unified API.

POST /api/generate-image

🎥 Video Generation

Grok Imagine, Wan 2.7, Hailuo 02, Seedance Pro/Lite, Kling 2.6 (audio), Kling 3.0 Standard/Pro/4K (audio), VEO 3.1, Happy Horse. T2V and I2V across all models.

POST /api/generate-video

Platform Endpoints

Generation Endpoints

Quick Start

import requests, time

headers = {"X-AW-Key": "aw_live_your_key_here", "Content-Type": "application/json"}
base    = "https://aetherwavestudio.com"

# 1. Generate an image
result = requests.post(f"{base}/api/generate-image", headers=headers, json={
    "prompt": "Dark synth album cover, neon sigils, molten orange",
    "model":  "grok-imagine-t2i",
    "aspectRatio": "1:1"
}).json()

# 2. Poll until complete
task_id = result["taskId"]
while True:
    status = requests.get(f"{base}/api/generate-image/status/{task_id}").json()
    if status["state"] == "SUCCESS":
        print(status["images"][0])  # → CDN image URL
        break
    time.sleep(3)

const res = await fetch("https://aetherwavestudio.com/api/generate-music", {
  method: "POST",
  headers: {
    "X-AW-Key": "aw_live_your_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "prompt": "Lo-fi ambient track, rain sounds, warm pads",
    "instrumental": true,
    "model": "V4_5"
  })
});

const { taskId } = await res.json();
// Poll /api/music-status/{taskId} until status === "complete"

curl -X POST https://aetherwavestudio.com/api/generate-image \
  -H "X-AW-Key: aw_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "neon cyberpunk album cover, glitch art", "model": "grok-imagine-t2i", "aspectRatio": "1:1"}'

# Returns taskId — poll status:
curl https://aetherwavestudio.com/api/generate-image/status/img_TASKID

What to expect back

Generation endpoints return a taskId immediately. Poll the status endpoint until state === "SUCCESS" (case-normalized server-side; any of success, complete, done from upstream map to SUCCESS in our response).

POST /api/generate-image

{
  "taskId": "img_1748547821934_a3k9p2qr",
  "message": "Image generation started",
  "creditsUsed": 5,
  "expectedImages": 6
}

GET /api/generate-image/status/:taskId

{
  "state": "PROCESSING",
  "status": "PROCESSING",
  "progress": 45,
  "creditCost": 5
}

{
  "state": "SUCCESS",
  "status": "SUCCESS",
  "images": [
    "https://media.aetherwavestudio.com/.../image-1.png",
    "https://media.aetherwavestudio.com/.../image-2.png"
  ],
  "autoSaved": true,
  "creationIds": ["creation_..."]
}

{
  "state": "FAILED",
  "status": "FAILED",
  "error": "Upstream model returned content-policy refusal"
}

POST /api/generate-video

{
  "taskId": "task_1748547821934_xqp9r2",
  "message": "Video generation started",
  "creditCost": 36,
  "duration": 6,
  "resolution": "720p"
}

{
  "state": "success",
  "data": {
    "video": {
      "url": "https://media.aetherwavestudio.com/.../video.mp4"
    },
    "fallbackProvider": null
  },
  "kieTaskId": "6d38d323d4070569c0bdf583956770d1",
  "creationId": "creation_...",
  "autoSaved": true
}

POST /api/generate-music

Two modes. The meaning of prompt changes between them, and that is the single most common source of confusion:

• Simple mode (customMode false, the default) — prompt is a description of the song, and Suno writes its own lyrics.
• Custom mode (customMode: true) — prompt is the literal lyrics, style carries the musical direction, and title is honoured.

There is no lyrics parameter. Sending one has no effect, and title is ignored outside custom mode. Every generation costs 20 credits and returns two tracks, on every model and every plan.

{
  "customMode": true,
  "prompt": "Verse 1:\nWalking through the neon rain\n...",  // literal lyrics
  "style": "Synthwave, dreamy, female vocals",
  "title": "Neon Rain",
  "vocalGender": "f",        // "m" or "f", default "m"
  "instrumental": false,
  "model": "V5_5"          // V3_5 | V4 | V4_5 | V5 | V5_5
}

{
  "prompt": "Dreamy lo-fi hip hop, vinyl crackle, rainy night",  // a description
  "instrumental": false,
  "model": "V5_5"
}

{
  "status": "complete",
  "tracks": [
    {
      "id": "suno_...",
      "audioUrl": "https://media.aetherwavestudio.com/.../track-1.mp3",
      "title": "...",
      "duration": 182.4
    },
    { /* second track, same shape */ }
  ]
}

One Credit Pool

Credits work the same whether you use the platform UI or the API. 1 credit = $0.005. Subscription credits refresh monthly and do not roll over. Bundle credits never expire. Subscription credits drain first.

Subscription Plans

Subscriptions charge immediately on the first month - there is no free trial.

Credit Bundles

One-time purchases. Never expire. Stack on top of any subscription.

Buy Credits →

Error Codes

SKILL.md Files (Claude, Cursor, Continue, any LLM)

Every AetherWave API ships with a .skill file — a structured Markdown document that teaches any LLM how to operate it. Drop the SKILL.md into your agent's context and it can call AetherWave APIs autonomously.

Works today with:

• Claude Code (CLI + SDK) — place SKILL.md files in ~/.claude/skills/<name>/ and they auto-load as invocable skills.
• Cursor / Windsurf / Continue — paste SKILL.md content into a project's agent context or rules file.
• Custom agents (LangChain, AutoGen, raw API) — include the SKILL.md content in the system prompt or tool description.

# In your agent's system prompt or tool context:

# 1. Load the SKILL.md
with open("music-generation.SKILL.md") as f:
    skill_context = f.read()

# 2. Pass to your LLM alongside the user's request
# The SKILL.md contains everything the model needs:
#   - Endpoint URLs and methods
#   - Request/response schemas
#   - Credit costs
#   - Error handling
#   - Authentication (X-AW-Key header)

Harness Engineering

AetherWave is pioneering harness engineering — the practice of designing creative AI workflows that non-technical founders can operate at a high technical level through AI agents.