@aetherwave-studio/mcp

Model Context Protocol server for AetherWave Studio. Drop it into any MCP-compatible client (Claude Code, Cursor, Continue, Claude Desktop, custom agents) and your LLM can generate, edit, upscale, reframe, and master across every flagship creative AI provider through one API key, one credit pool.

One install. One token. Thirty-five default tools covering:

• Music - Suno V3.5 / V4 / V4.5 / V5 / V5.5 / V6

• Image gen - Grok Imagine, GPT Image 2, Seedream V4, Wan 2.7, Nano Banana 2, Flux 2, Qwen Image, Z-Image Turbo

• Image edit - Grok Imagine I2I, Seedream V4 Edit, Flux Kontext, Wan 2.5 Spicy, Qwen Edit, GPT Image 1.5

• Image utility - 2x / 4x upscale, Recraft background removal (with fal BiRefNet v2 fallback), Reframe (outpaints to a new aspect ratio)

• Video - Grok Imagine (KIE+fal fallback), Wan 2.7, Hailuo 02, Seedance Pro/Lite, Kling 2.6 (audio), VEO 3.1, Happy Horse

• Video utility - Atlas upscaler (1080p/2K), rembg u2netp background removal, Luma Ray 2 Flash reframe

• Audio mastering - 12 genre/style presets via the AetherWave Python service

• Voiceover - text to speech in 9 voices on Fish Audio, 5 credits per 1,000 characters

• Gallery - upload your own images, audio and video (local file, URL or data URL), and a paginated list of your saved creations

• User manuals - the MCP, Graphic Novel Studio, UGC Studio and Project Studio manuals as PDF links (saved to Downloads on the npx server)

• Comic books - 9 tools driving the AetherWave Graphic Novel Engine end to end: cast, character references, script, panels, lettered pages, and a PDF / EPUB / CBZ download link

• Merch - 4 tools: garment catalog, design-to-mockup, and (with PRINTFUL_API_TOKEN) 2 more that create and list products in your own Printful store, plus 1 admin shop-listing tool

Every generation tool submits the job and waits up to a soft 45 s deadline for the result. Fast jobs come back with the final URL in one round-trip; anything longer returns state: "running" with a taskId, and aetherwave_get_job covers every pipeline (image, video, music, mastering, comics, merch) for polling. Pass async: true on any tool to return immediately. Results auto-save to your Cloudflare R2 gallery so URLs don't expire.

The comic tools are built around this from the start: a book takes about an hour to draw, so each slow step starts and returns at once, and aetherwave_comic_status is how the agent checks back. See Make a comic book with the MCP.

Quick start

# 1. Get a key at https://aetherwavestudio.com/profile (Developer tab)
# 2. Add to your MCP client config (see below)
# 3. Restart the client
# 4. Ask your agent to "generate a synthwave album cover, then animate it"

Claude Code

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

Claude Desktop

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

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

Restart Claude Desktop.

Cursor

In Cursor Settings -> MCP -> Add new server:

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

Continue (VS Code / JetBrains)

In your ~/.continue/config.yaml:

mcpServers:
 - name: aetherwave
    command: npx
    args: ["-y", "@aetherwave-studio/mcp"]
    env:
      AETHERWAVE_API_KEY: aw_live_...

Custom / programmatic clients

Standard stdio MCP server. Any client that speaks JSON-RPC 2.0 over stdio per the MCP spec can connect:

AETHERWAVE_API_KEY=aw_live_... npx -y @aetherwave-studio/mcp

Related MCP server: Google Veo 3.1 MCP Server

Tools at a glance

Every generation tool includes a model-selection rubric in its description. Your agent can pick the right model from prompt intent without round-tripping list_image_models or list_video_models.

Make a comic book with the MCP

Nine tools drive the AetherWave Graphic Novel Engine from start to finish, so an agent can turn one sentence into a finished, lettered comic. You say something like:

Make me a 12-page Franco-Belgian adventure comic about a 14-year-old courier and her grumbling mechanic uncle who fly the village's last airmail balloon over the Alps at night to deliver a letter that stops a dam from flooding their home. All ages. Keep it under 350 credits.

and the agent runs this sequence:

Measured on a real book

"The Last Balloon Post" (2026-09-25) was made exactly this way, through the same API these tools call:

• 12 pages, 27 panels, 301 credits: 27 panels x 9 = 243, script 40, three character references 18. The estimate had quoted 462, because it assumes 48 panels for 12 pages. Re-quote from creditsToFinishDrawing once the script exists.

• About 65 minutes of drawing, 1.5 to 6 minutes a panel, strictly one after another. About 80 minutes end to end.

• 9 panel failures along the way, none charged: 3 content-filter refusals, 4 upstream "Internal Error" flakes, 2 panels cut off when the server restarted. Every one was drawn on a later run.

• Assembly took about 45 seconds for 12 pages. The PDF was 130 MB, which is why export returns a link rather than the file.

Rules the agent should follow

• Approve references before writing the script. Approving re-describes the character from the picture, and the script writer reads that description. A character with no approved reference is drawn from text alone and their face drifts between panels.

• Never treat a stopped run as finished. A server restart ends a drawing run silently. aetherwave_comic_status reports drawing: "stalled" whenever panels are pending or failed and no run is active. aetherwave_comic_draw is safe to call again: it draws only what is missing and never double-starts (a second start reports alreadyDrawing).

• Reword, do not retry, a refused panel. failedPanels[].errorMessage in the status carries the reason. A content refusal repeats on a plain retry; aetherwave_comic_redraw_panel with a new prompt replaces the scene description for that drawing. Scenes of physical contact between an adult and a child are refused by the image filter.

• Rewriting the script deletes every panel. aetherwave_comic_write_script refuses on a project that has panels unless replaceExisting: true.

• Re-assemble after a redraw on a page that was already assembled; aetherwave_comic_status lists those pages under pages.staleSinceAssembly.

• Only permanent images can be references. approve refuses temporary links (for example a raw provider result URL), because the book would break when the link expires.

• Every comic tool result carries account: the AetherWave username that is paying. Check it if you run more than one MCP connection.

Programmatic video with your own characters

The tools above compose into something the API could not do before: hand an agent a description and get back a finished multi-shot film, starring a character you already created, with one consistent face and voice throughout.

A UGC character is a recurring on-screen person you have saved in AetherWave - their locked appearance, an approved pack of reference images, a voice and a personality. aetherwave_list_characters is how an agent discovers they exist. Without it, an agent told "shoot this with my Amy character" has no way to learn who Amy is, and invents a different face for every clip.

Shortcut (0.4.0): pass character: "Amy" to aetherwave_generate_image or aetherwave_generate_video and the tool does steps 1 to 3 for you: it looks the character up in your teams, puts their approved reference pack first in referenceImages (your own references, such as a T-shirt or a location, go after), and appends their identityBlock verbatim. On generate_image the model defaults to gpt-image-2-t2i, which takes up to 16 references. A name that matches nothing, or more than one character, is an error that lists the names you do have, and nothing is charged.

// "Put Amy in this T-shirt, facing forward" - one call
await generateImage({ prompt: "Amy wearing this T-shirt, facing forward, clean studio background", character: "Amy", referenceImages: [shirtMockupUrl], aspectRatio: "3:4" });

The loop

// 1. Discover the character. There is no other way to find them.
const { characters } = await listCharacters({ name: "amy" });
const amy = characters[0];

// 2. Build every prompt from her stored identity - VERBATIM, never paraphrased.
//    Identical text is identical conditioning; that IS the consistency mechanism.
const prompt = [
  shotDescription,
  amy.identityBlock,                    // "CORE IDENTITY: same woman, Nordic, ..."
  `Her speaking voice: ${amy.voiceSpec ?? amy.voiceDescriptor}`,
  `She says exactly this and nothing else: "${line}"`,
].join("\n\n");

// 3. Submit async, anchored to her approved pack, with audio on.
const { taskId } = await generateVideo({
  prompt,
  model: "seedance-2-mini",
  duration: 12,
  resolution: "480p",
  aspectRatio: "16:9",
  generateAudio: true,                  // without this the clip is SILENT
  referenceImages: amy.referenceImages, // NOT imageUrl - that drops the anchors
  async: true,                          // returns in ~2s, survives the client timeout
});

// 4. Poll until the render lands.
let job;
do { await sleep(15000); job = await getJob({ taskId, kind: "video" }); }
while (!job.done && !job.error);

// 5. Repeat per shot, then assemble the clips in order.

The four rules that actually keep a character consistent

1. Append identityBlock verbatim to every prompt. Rewriting it in your own words breaks the lock - identical text is the whole mechanism.

2. Pass referenceImages, never imageUrl. A first frame switches the engine to first-frame mode and discards the anchors. When a character has an approved pack, that pack replaces the hero image rather than riding alongside it; mixing them pulls the face two ways.

3. Keep the voice text byte-identical across clips, for the same reason as the identity block.

4. Set generateAudio: true on anything with dialogue. It is off by default and free on Seedance 2.x, so a silent clip is never the cheaper choice - just a worse one.

Writing lines to length

duration is authoritative. The engine honours the seconds you ask for to within ~0.1s and then fits the line to that length by changing pace, rather than finishing early. So write the line to the clip, not the clip to the line - roughly 2 words per second is the measured working figure. A words-per-minute number in a voice description describes the character, not the engine; budgeting by it overran a 22-clip production by 35%.

Spell hard words the way they should be spoken: "super intelligence" renders more reliably than "superintelligence".

⚠️ Verify the speech before you assemble

A take can come back saying the wrong words and still report success with a URL. Re-rendering an identical prompt has produced one clean take and one that dropped an entire sentence - it is per-take randomness, and nothing in the response distinguishes them. On a 22-clip production, four clips were mis-spoken and none was detectable without listening.

For anything assembled unattended, transcribe each clip and score it against the line you asked for before using it, and re-shoot the ones that fail. Checking costs nothing; the clip already cost credits. Score against the script, not against whatever the previous step handed you.

Sell merch from a conversation (Printful)

Turn any design into a print-on-demand product by asking for it:

"Make a tee that says NIGHT SHIFT in chrome letters, put it on a black Bella+Canvas 3001, show me mockups, then add it to my Printful store at $29.99."

Connect your Printful store

Add your Printful token to the server's env. It is used only between your machine and api.printful.com; it never goes to AetherWave.

{
  "mcpServers": {
    "aetherwave": {
      "command": "npx",
      "args": ["-y", "@aetherwave-studio/mcp"],
      "env": {
        "AETHERWAVE_API_KEY": "aw_live_...",
        "PRINTFUL_API_TOKEN": "your Printful private token",
        "PRINTFUL_STORE_ID": "only needed for account-level tokens"
      }
    }
  }
}

Create the token in Printful under Settings > API (a private token scoped to one store is simplest). The two aetherwave_printful_* tools appear only when PRINTFUL_API_TOKEN is set, and only on the local npx server: the remote connector never asks for your store key. Products land in Printful; publishing to Shopify, Etsy and other connected channels happens there as usual.

Before you promote a product: Printful charges per order (garment, shipping, and in the US often sales tax). Check that your retail price covers it. You are the seller: only print artwork and wording you have the rights to.

Printify: coming next. Its catalog works differently (the same garment from several print providers, with their own prices and stock), so it gets its own tools rather than a half-working flag.

Tools reference

aetherwave_balance

Returns current credit balance. No inputs.

Returns: { credits, plan, ... }

aetherwave_list_image_models

Returns every image model with credit cost, supported inputs, resolution/aspect options. No inputs.

Returns: { models: [...] }

aetherwave_list_video_models

Returns every video model with per-second credit cost, durations, resolutions, aspect ratios. No inputs.

Returns: { models: [...] }

aetherwave_list_master_presets

Returns every mastering preset with target LUFS, tags, descriptions, difficulty. No inputs. Call this before master_audio when you don't know which preset fits the track.

Returns: { presets: [...] } (each: { id, name, description, target_lufs, tags, difficulty, icon })

aetherwave_generate_image

T2I or I2I. Submits, polls, returns final URLs.

Selection signals (built into the tool description): single best image → gpt-image-2-t2i (9 cr at 1K, 12 at 2K). Photoreal → gpt-image-2-t2i or nano-banana-2. Text-in-image → gpt-image-2-t2i. NSFW → wan-2.5-spicy-t2i. Premium → grok-imagine-quality-t2i (14 cr). Cheapest → z-image-turbo (2 cr).

Returns: { taskId, state, images, autoSaved, creationIds }

aetherwave_list_characters

Your saved UGC characters - the recurring, named people you shoot with - with everything needed to hold one consistent across a production. Call this first whenever a request names a person the user already has.

Returns: { count, characters[], usage }, each character carrying:

Long jobs return within 45 seconds

MCP clients (claude.ai, Claude Desktop, Cursor) abandon a tool call at about 60 seconds. Before 0.3.0 every long tool blocked for 6 to 15 minutes, so a 90-second image render "failed" on the client while the job finished and was charged, and the taskId died with the abandoned call.

Now every tool that submits a job (generate_image, edit_image, upscale_image, reframe_image, remove_background, generate_video, upscale_video, reframe_video, remove_background_video, generate_music, merch_mockup, comic_export) polls for at most ~45 seconds and then returns:

{ "state": "running", "taskId": "…", "kind": "image", "checkWith": "aetherwave_get_job", "pollEverySeconds": 10, "next": "…" }

Poll aetherwave_get_job with that taskId and kind until done. Two explicit escapes on each of those tools:

master_audio has no job id (the request itself is the job): it also returns within ~45 s, and a master that outlives the call is saved to the gallery - find it with aetherwave_list_my_creations type audio rather than resubmitting.

aetherwave_get_job

Check a job by taskId. Use it for any state: "running" result, after an async: true submit, or to recover any generation whose call timed out, since the job keeps running server-side and saves to your gallery regardless of what happened to the client.

Returns: { taskId, kind, state, done, failed, videoUrl, imageUrls, tracks, mockups, downloadUrl, autoSaved, creationIds, error, next, raw }

aetherwave_generate_video

T2V or I2V. Submits, polls for up to ~45 s, and returns the URL if the render finished - otherwise state: "running" with the taskId (video takes 1-8 min, so that is the usual case).

Returns (finished): { taskId, state, videoUrl, fallbackProvider, autoSaved, creationId, kieTaskId } Returns (still rendering, or async): { state: "running", taskId, kind: "video", checkWith, pollEverySeconds, next }

A render takes 1-8 minutes and most MCP clients abandon a call at 60 seconds (MCP error -32001), so this tool returns state: "running" within ~45 s and you poll aetherwave_get_job. The job itself is submitted, billed and saved to your gallery regardless of what the client does.

⚠️ imageUrl and referenceImages are not additive. A supplied first frame switches the engine to first-frame mode exclusively and drops the reference images - which silently disables the only no-drift mechanism available. Passing both is rejected with an explicit error rather than quietly honouring one.

aetherwave_generate_music

Suno music generation. Two tracks per submission.

Returns: { taskId, status, tracks }

aetherwave_edit_image

I2I editing guided by a text prompt.

Selection signals: subtle edits / character consistency → flux-kontext-pro. NSFW → wan-2.5-spicy-i2i. Highest quality → gpt-image-1.5-i2i or grok-imagine-quality-i2i. Single-output / 4K → seedream-v4-edit.

URL gotcha: source URLs with spaces or parentheses may fail upstream. Prefer clean URLs without special characters.

Returns: { taskId, state, images, autoSaved, creationIds }

aetherwave_upscale_image

Upscales 2x or 4x for a flat 4 credits.

Credit cost scales with source resolution × factor.

Returns: { taskId, state, images, autoSaved, creationIds }

aetherwave_reframe_image

Reframe. Outpaints edges to fit a new aspect ratio: the source is kept whole and centred, new picture is painted on the two sides that grow, and nothing is cropped. 12 credits per image, flat. The output size follows the source (capped at 4096 px on the long edge), so resize afterwards if you need exact pixels.

Returns: { taskId, state, images, autoSaved, creationIds }

aetherwave_remove_background

Recraft primary + fal.ai BiRefNet v2 fallback. ~5 cr per image.

Returns: { taskId, state, images } (PNG with transparent alpha)

aetherwave_upscale_video

Two engines. Atlas reaches 1080p and 2K; BytePlus reaches 1080p, 2K, 4K and 8K and is selected automatically for 4K and 8K.

A tier is not a dimension: the names are 16:9 standards, so the source is fitted inside the tier's box and the smaller dimension wins. A square source at 4k returns 2160x2160, not 3840x3840. For an exact pixel target, take the highest sensible tier and resize in ffmpeg.

Returns: { taskId, status, videoUrl, autoSaved, creationId }

aetherwave_remove_background_video

Frame-by-frame background removal via rembg u2netp on AetherWave's Python service. 2 cr/sec.

Returns: { taskId, status, videoUrl, autoSaved, creationId }

aetherwave_reframe_video

Luma Ray 2 Flash reframe to a new aspect ratio. 17 cr/sec.

Returns: { taskId, status, videoUrl, autoSaved, creationId }

aetherwave_master_audio

AI mastering via the AetherWave Python service. Synchronous response (route polls internally, expect 30s-5min). 20 credits per track. Free on Artist, Producer, Mogul and Ultimate plans. Output is WAV (~50MB per 3-min track) and auto-rehosted to Cloudflare R2.

Preset list (12, retrieved live from /api/master-presets):

Returns: { success, masteredUrl, preset, trackTitle, creditsCharged, isFree }

aetherwave_upload_to_gallery

Saves a file the user already has into their AetherWave gallery and returns a permanent URL that every other tool accepts. Free (no credits); it counts against the account's storage, and an upload over the plan's storage is refused with the space left.

Types: images png jpg webp gif, audio mp3 wav m4a flac ogg, video mp4 webm mov. Up to 95 MB per file; larger files go through the website uploader.

Returns: { success, creationId, url, type, title, sizeBytes }

aetherwave_get_user_manual

The download link for a user manual PDF. On the npx server it also saves the PDF to the user's Downloads folder (or saveTo), and returns the path. Free.

Returns: { manual, title, url, savedTo?, sizeBytes? }

aetherwave_generate_speech

Turns text into a spoken MP3 on Fish Audio (s2.1-pro): narration, an ad read, a podcast intro, a character line. Synchronous on the platform, usually a few seconds. Charged when the request is accepted, refunded automatically if no audio is delivered; saved to the gallery as audio. The tool reads the exact price from POST /api/v1/audio/speech/estimate first, so an unknown voice or a too-long text fails before anything is spent.

Price: 5 credits per 1,000 characters, minimum 2, billed per UTF-8 byte (plain English is one byte per character; accented and non-Latin text costs up to 3x).

Returns: { success, audioUrl, voice, durationSec, creationId, creditsUsed, creditsRemaining }. If the call outlives ~45 s you get state: "running"; the voiceover lands in aetherwave_list_my_creations type audio. Do not resubmit.

aetherwave_list_voices

Free. The 9 voices with a short description, the default voice, the price and the per-call limit.

aetherwave_list_my_creations

Paginated gallery read. Useful for chaining ("reframe my last 5 images to 9:16").

Returns: { items, total, offset, limit, hasMore }. Each item: { id, type, title, prompt, model, createdAt, isFavorite, contentUrl, thumbnailUrl, visibility, rating, duration?, width?, height?, likeCount, totalPlays, metadata }.

Comic book tools

All nine wrap the /api/graphic-novel/* routes the Graphic Novel Studio web app uses, so a book made through the MCP opens in the studio and the reverse. Every result includes account, the username that is billed.

aetherwave_comic_estimate

Free upper-bound quote. Assumes 4 panels a page, so short books usually cost less (12 pages: quoted 462, cost 301).

Returns: { account, scriptCredits, panelCredits, assumedPanels, creditsPerPanel, totalCredits, imageModel, note }

aetherwave_comic_create

Creates the project and its cast. Free. Nothing is generated yet.

Returns: { account, projectId, status, characters: [{ characterId, name, role }], estimate, nextStep }

aetherwave_comic_character_reference

action: "generate" draws count (1-4) full-body references in the book's style, 6 credits each, and adds them to the character's options. editPrompt alone steers a fresh drawing; editPrompt with baseUrl (one of the character's images) edits that image and keeps the same person. If the call runs past about 50 seconds the images still land server-side and show up in aetherwave_comic_status.

action: "approve" (free) sets imageUrl as the reference. Only the character's own images or permanent AetherWave storage (media.aetherwavestudio.com) are accepted.

Returns (generate): { account, characterId, characterName, newImages, creditsCharged, stillGenerating, errors, referenceOptions, nextStep }. Returns (approve): { account, approved, characterId, characterName, referenceImageUrl }

aetherwave_comic_write_script

Starts the script and returns. About 2 to 3 minutes; charged on actual use when it finishes (40 credits for the 12-page book). Refuses on a project that already has panels unless replaceExisting: true, because a new script deletes them all.

Returns: { account, started, status, message, warning?, nextStep }. warning names characters with no approved reference.

aetherwave_comic_draw

action: "start" (default) starts drawing every pending or failed panel, one at a time, and returns. 9 credits a panel, charged only on success; the balance must cover the whole run to start. Calling it while a run is active starts nothing and reports alreadyDrawing. action: "stop" asks the active run to stop after its current panel.

Returns: { account, started, panelsQueued, creditsPerPanel, upToCredits, message, expectedMinutes, nextStep }, or { started: false, alreadyDrawing: true }

aetherwave_comic_status

Free. The one tool to poll. With no projectId it lists your recent comic projects.

Returns: { account, projectId, title, projectStatus, projectError, drawing, drawingDetail, panels: { total, completed, failed, pending, generating, batchRunning }, creditsToFinishDrawing, failedPanels: [{ panelId, page, panelIndex, errorMessage, scene }], pages: { total, assembled, missing, staleSinceAssembly, urls }, characters: [{ characterId, name, role, approvedReference, referenceOptions }], nextStep }

drawing is one of no_script, not_started, drawing, redrawing, stalled, done. stalled means panels are pending or failed and no run is active; call aetherwave_comic_draw again.

aetherwave_comic_redraw_panel

Redraws one panel. 9 credits on success, nothing on failure. prompt replaces the panel's scene description for this drawing (dialogue and captions are kept), which is how to get past a content refusal. Refused while a full run is active. If the redraw outlasts about 50 seconds the tool returns stillDrawing: true and the result appears in aetherwave_comic_status.

Returns: { account, redrawn, panelId, status, imageUrl }, { redrawn: false, stillDrawing: true }, or a refusal carrying the panel's errorMessage

aetherwave_comic_assemble

Free. Lays out and letters every page, about 4 seconds a page, and returns at once. Refuses while panels are drawing, and refuses while any panel is undrawn unless allowPartial: true (pages with an undrawn panel are skipped and the book is marked pages-partial).

Returns: { account, started, pages, message, nextStep }

aetherwave_comic_export

Free. Builds the assembled book and returns a download link on AetherWave storage that lasts about a day. Usually finishes within the call (a 12-page PDF took about 15 seconds to build and upload in testing); otherwise it returns an exportId to check with a second call. One export builds per account at a time: if one is already building, the tool reports that one (alreadyExporting: true, with its projectId) instead of starting another. When the service is busy it refuses with retryAfterSeconds.

Returns: { account, exportId, format, status, url, megabytes, note }. status is building, complete or error.

Embedding the tools in your own server

@aetherwave-studio/mcp/embed runs the same tools in-process, so an assistant you host gets every tool, schema and description this server has and picks up new ones with a package update. AetherWave's own VoxBot Chat is built on it.

import { connectEmbedded, runsWithoutConfirm } from "@aetherwave-studio/mcp/embed";

const session = await connectEmbedded({
  baseUrl: "https://aetherwavestudio.com",
  headers: { "X-AW-Key": userApiKey },            // or the member's session headers on a loopback URL
  allowRequest: (method, path) => isAllowed(method, path), // optional (method, path) allowlist
});
session.tools;          // [{ name, description, inputSchema, policy }], operator-only tools left out
if (runsWithoutConfirm(name)) await session.call(name, args); // free reads
// anything else spends credits or replaces something: quote it and get the user's OK first

Every tool carries a policy (TOOL_POLICY): charge ("none" or "credits", with a note on how the price is known up front), effect ("read", "create" or "destructive") and embed (false for tools that need the operator's own tokens). A test fails the build if a tool ships without one. Importing the module never starts the stdio server.

Credits & pricing

AetherWave uses a single credit pool. Buy bundles starting at $4.99 / 500 credits (bundle credits never expire) or subscribe to Studio ($9.99/mo, 1,700 credits; no free trial, billing starts at signup). Both work for API calls.

Typical costs:

• Image gen - 2 cr (Z-Image Turbo) to 34 cr (premium models at 4K); default 6 cr for 2 images

• Image edit - 6 cr to 34 cr; default 10 cr (Grok Imagine I2I)

• Image utility - 4 cr (2x or 4x upscale), 5 cr (background removal), 12 cr (reframe, flat)

• Video - 4 cr/sec (Grok Imagine at 480p) up to 143 cr/sec (Seedance 2 at 1080p); VEO 3.1 is a fixed 42 / 84 / 350 cr per 8 s clip

• Music - 20 cr per generation (2 tracks)

• Mastering - 20 cr/track (free on Artist / Producer / Mogul / Ultimate)

• Voiceover - 5 cr per 1,000 characters, minimum 2

• Comic books - 9 cr a panel (charged on success), 6 cr a character reference, script charged on use (about 40 cr for 12 pages). A 12-page, 27-panel book cost 301 cr

See live pricing at https://aetherwavestudio.com/buy-credits or via aetherwave_list_*_models.

Environment variables

Troubleshooting

"AETHERWAVE_API_KEY environment variable is required" Your MCP client isn't passing the env var. Make sure the env block in your client config has AETHERWAVE_API_KEY set. After editing config, fully restart the client.

"AetherWave API ... failed: 401 - Invalid API key" The key has been revoked or regenerated. Visit https://aetherwavestudio.com/profile -> Developer tab and copy a fresh key.

"AetherWave API ... failed: 402 - Insufficient credits" Your balance is too low for the requested operation. Call aetherwave_balance to confirm, then top up at https://aetherwavestudio.com/buy-credits.

"AetherWave generation timed out after Xs" The provider is queueing. The job may still complete server-side - check the AetherWave gallery at https://aetherwavestudio.com/gallery.html. If timeouts persist for a particular model, try a different one (e.g. switch from grok-imagine-t2v to wan-2-7-t2v, or gpt-image-1.5-i2i to grok-imagine-i2i).

Reframe fails before it starts The source must be a public https link the platform can download. Upload a local file with aetherwave_upload_to_gallery first and pass the URL it returns. An aspectRatio outside the list in the tool is refused before any credit is charged.

"internal error, please try again later" on remove_background KIE Recraft transient outage. The tool will auto-fall-back to fal.ai BiRefNet v2 on retry, but a single call returning this error means both providers refused. Wait a minute and retry.

Comic status says drawing: "stalled" The drawing run ended with panels left: a server restart, the balance ran out, or it was stopped. Call aetherwave_comic_draw again; it draws only the missing panels and charges only for panels that succeed.

A comic panel keeps failing with "may violate our content policies" Retrying the same scene gets the same refusal. Reword it with aetherwave_comic_redraw_panel and a new prompt. Physical contact between an adult and a child is refused even in an all-ages book.

aetherwave_comic_export says the server "does not support export links yet" The AetherWave server you are pointed at predates export links. Download the book from the Graphic Novel Studio in the web app.

Soul Forge band generation Not exposed via MCP. Soul Forge remains a consumer feature on the web at https://aetherwavestudio.com/soul-forge.

Versioning

This package follows semver. Tools that change behavior in a breaking way will bump the major version. New tools and additive parameters bump the minor version. Bug fixes bump the patch version.

0.5.5: aetherwave_reframe_image matches the platform's new Reframe (since 2026-11-11): one flat price of 12 credits, eleven exact shapes (adds 3:2, 2:3, 5:4, 4:5, 9:21), and the ratio is sent as given. speed is accepted and ignored; the old 5 / 10 / 14 tiers are gone.

0.5.4: a "not enough credits" error now carries the platform's next step (how short you are) and a one-tap link to the right credit pack, the cheapest one that covers the shortfall.

0.5.3: aetherwave_generate_speech waits 49 s (the platform's voice provider times out at 45 s, so a refunded call no longer reads as still running), and a failure says whether the credits were refunded (state: "failed", refunded), or state: "unknown" when the connection dropped mid-call.

0.5.2: aetherwave_generate_music adds Suno V6 and makes it the default (the website default too). Same 20 credits as every other version.

0.5.1: aetherwave_generate_music sends title on an instrumental (it was dropped, and Suno named the track itself), and a lyric request without a title no longer fails with "Title and Style are required in Custom Mode" (the title defaults to the start of the description).

0.5.0: aetherwave_generate_speech and aetherwave_list_voices, voiceover on Fish Audio (9 voices, 5 credits per 1,000 characters). 35 default tools.

0.4.0: character on aetherwave_generate_image and aetherwave_generate_video (one of your UGC characters by name). Image count: generate_image now sends maxImages, the field the platform reads (numImages, which no model read, is kept as an alias). A reference URL that resolves to a private address is refused. New @aetherwave-studio/mcp/embed entry for hosting the tools inside another server (see Embedding).

0.3.1 (unreleased, folded into 0.4.0): aetherwave_upload_to_gallery and aetherwave_get_user_manual, 33 default tools.

0.3.0 (2026-09-30): soft 45 s deadline on every long tool (returns state: "running" + taskId instead of timing out the client), async: true on every tool, aetherwave_get_job covers all pipelines, 9 comic tools, 4 merch tools (+2 Printful tools with PRINTFUL_API_TOKEN, +1 admin), 31 default tools.

The MCP protocol version itself (currently 2024-11-05) is negotiated at handshake time by the SDK; no client config needed.

Links

• AetherWave Studio: https://aetherwavestudio.com

• Developer docs: https://aetherwavestudio.com/developers

• Get an API key: https://aetherwavestudio.com/profile (Developer tab)

• Buy credits: https://aetherwavestudio.com/buy-credits

• GitHub: https://github.com/AetherWave-Studio/aetherwave-mcp

• npm: https://www.npmjs.com/package/@aetherwave-studio/mcp

License

MIT. See LICENSE.